---
schema_version: "1"
id: 56c3b9965567ce52188d789d8cc147cbd99a8c57020f9dc3f13d8702abb8de77
title: Stores
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/stores.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/stores
source_site: developer.salesforce.com
content_type: documentation
content_hash: 8b017dbb32f477c7b8c509c5cdda1f6818c3d9bbc38667b7df0f943be42e6537
products:
  - B2C Commerce API
  - Salesforce APIs
---
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"
  ]
}
```