Salesforce B2C Commerce 24.7 > Open Commerce API 23.2 > Shop API resources 23.2

Stores resource (Shop API 23.2)

Summary

Http Method	Resource	Description
GET	/stores	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.
GET	/stores/({id},...,{id})	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.
GET	/stores/{id}	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.

Http Method

Resource

Description

GET

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.

GET

/stores/({id},...,{id})

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.

GET

/stores/{id}

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.

Get nearest stores

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.

Url

GET http://hostname:port/dw/shop/v23_2/stores?latitude={Decimal}&longitude={Decimal}&country_code={String}&postal_code={String}&distance_unit={String}&max_distance={Decimal}&start={Integer}&count={Integer}

Formats

json, xml

Authentication

Name	Description
JWT	Authentication via Customer JWT.
None	No authentication.

Response Document

StoreResult

Query Parameters

Parameter	Type	Description	Constraints
count	Integer	The maximum number of instances per request. Default value is 25.	maxIntegerValue=200, minIntegerValue=1
country_code	String	The two letter ISO country code e.g. \"US\".	maxLength=2, minLength=2
distance_unit	String	The distance unit. Supported values are \"mi\" and \"km\" (for miles and kilometers respectively, default is \"km\").
latitude	Decimal	The geo coordinate latitude to search for stores (value range -90.00 .. 90.00).	maxNumberValue=90.0, minNumberValue=-90.0
longitude	Decimal	The geo coordinate longitude to search for stores (value range -180.00 .. 180.00).	maxNumberValue=180.0, minNumberValue=-180.0
max_distance	Decimal	The area (radius) in distancUnit where stores will be searched for (default is half of the earth's perimeter).	maxNumberValue=20012.0, minNumberValue=0.0
postal_code	String	The postal code e.g. \"01801\".	maxLength=10, minLength=3
start	Integer	The result set index to return the first instance for. Default value is 0.	minIntegerValue=0

In case of a failure Fault Document is returned.

Faults

Status	Type	Description
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..
400	`MissingCoordinatesException`	Thrown if only one of latitude or longitude are provided.
400	`MalformedDistanceUnitException`	Invalid distance_unit given.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.stores.modifyGETResponse	modifyGETResponse (doc : StoreResult ) : Status The function is called after the request has been processed. Parameters: doc - the document Returns: a non-null Status ends the hook execution
dw.ocapi.shop.stores.beforeGET	beforeGET (latitude : Double , longitude : Double , countryCode : String , postalCode : String ) : Status The function is called before the request will be processed. Parameters: latitude - The geo coordinate latitude to search for stores (value range -90.00 .. 90.00). longitude - The geo coordinate longitude to search for stores (value range -180.00 .. 180.00). countryCode - The two letter ISO country code e.g. "US". postalCode - The postal code e.g. "01801". Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.stores.modifyGETResponse

modifyGETResponse (doc : StoreResult ) : Status

The function is called after the request has been processed.

Parameters:: doc - the document
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.stores.beforeGET

beforeGET (latitude : Double , longitude : Double , countryCode : String , postalCode : String ) : Status

The function is called before the request will be processed.

Parameters:: latitude - The geo coordinate latitude to search for stores (value range -90.00 .. 90.00).; longitude - The geo coordinate longitude to search for stores (value range -180.00 .. 180.00).; countryCode - The two letter ISO country code e.g. "US".; postalCode - The postal code e.g. "01801".
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/stores?country_code=US&postal_code=02108&distance_unit=mi&max_distance=10.00&start=0&count=4 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
Content-Length: 1328

{
  "_v" : "23.2",
  "_type" : "store_result",
  "count" : 4,
  "data" : [ {
    "address1" : "333 Washington St",
    "city" : "Boston",
    "country_code" : "US",
    "distance" : 0.0,
    "distance_unit" : "mi",
    "email" : "[email protected]",
    "id" : "store10",
    "name" : "Downtown TV Shop",
    "phone" : "+1-617-695-1565",
    "postal_code" : "02108",
    "state_code" : "MA",
    "store_locator_enabled": true,
    "pos_enabled": false
  }, {
    "address1" : "1001 Cambridge St",
    "city" : "Cambridge",
    "country_code" : "US",
    "distance" : 1.41,
    "distance_unit" : "mi",
    "email" : "[email protected]",
    "id" : "store4",
    "name" : "Champaign Electronic Shop",
    "phone" : "+1-617-714-2640",
    "postal_code" : "02141",
    "state_code" : "MA",
    "store_locator_enabled": true,
    "pos_enabled": false
  }, {
    "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",
    "postal_code" : "02118",
    "state_code" : "MA",
    "store_locator_enabled": true,
    "pos_enabled": false
  }, {
    "address1" : "363 Hancock St",
    "city" : "North Quincy",
    "country_code" : "US",
    "distance" : 6.56,
    "distance_unit" : "mi",
    "email" : "[email protected]",
    "id" : "store3",
    "name" : "Wire-Wire",
    "phone" : "+1-617-318-2860",
    "postal_code" : "02171",
    "state_code" : "MA",
    "store_locator_enabled": true,
    "pos_enabled": false
  } ],
  "next" : "http://example.com/dw/shop/v23_2/stores?count=4&start=4&country_code=US&postal_code=02108&distance_unit=mi&max_distance=10.00",
  "start" : 0,
  "total" : 8
}

Get multiple stores

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.

Url

GET http://hostname:port/dw/shop/v23_2/stores/({id},...,{id})

Formats

json, xml

Authentication

Name	Description
JWT	Authentication via Customer JWT.
None	No authentication.

Response Document

StoreResult

Path Parameters

Parameter	Type	Description	Constraints
ids	[String]	The ids of the requested stores.	mandatory=true, maxItems=50, maxLength=256, nullable=false

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.store.modifyGETResponse	modifyGETResponse (scriptStore : Store , doc : Store ) : Status The function is called after the request has been processed. Parameters: scriptStore - an instance of dw.catalog.Store doc - the document Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.store.modifyGETResponse

modifyGETResponse (scriptStore : Store , doc : Store ) : Status

The function is called after the request has been processed.

Parameters:: scriptStore - an instance of dw.catalog.Store; doc - the document
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/stores/(02108-21,03104-3) 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
Content-Length: 431
{
  "_v" : "23.2",
  "_type" : "store_result",
  "count":2,
  "total":2,
  "data":
  [
    {
      "address1" : "333 Washington St",
      "city" : "Boston",
      "country_code" : "US",
      "email" : "[email protected]",
      "id" : "02108-21",
      "name" : "Downtown TV Shop",
      "phone" : "+1-617-695-1565",
      "postal_code" : "02108",
      "state_code" : "MA",
      "store_locator_enabled": true,
      "pos_enabled": false
    },
    {
      "address1" : "239 Bridge St",
      "city" : "Manchester",
      "country_code" : "US",
      "id" : "03104-3",
      "name" : "Gardena Mart",
      "phone" : "+1-603-715-9773",
      "postal_code" : "03104",
      "state_code" : "NH",
      "store_locator_enabled": true,
      "pos_enabled": false
    }
  ]
}

Get store

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.

Url

GET http://hostname:port/dw/shop/v23_2/stores/{id}

Formats

json, xml

Authentication

Name	Description
JWT	Authentication via Customer JWT.
None	No authentication.

Response Document

Store

Path Parameters

Parameter	Type	Description	Constraints
id	String	The id of the requested store.	mandatory=true, maxLength=256, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description

404

Status	Type	Arguments	Description
404	`StoreNotFoundException`	storeId (String) siteId (String)	Thrown if the requested store was not found

StoreNotFoundException

storeId (String)

siteId (String)

Thrown if the requested store was not found

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.store.modifyGETResponse	modifyGETResponse (scriptStore : Store , doc : Store ) : Status The function is called after the request has been processed. Parameters: scriptStore - an instance of dw.catalog.Store doc - the document Returns: a non-null Status ends the hook execution
dw.ocapi.shop.store.beforeGET	beforeGET (id : String , siteId : String ) : Status The function is called before the request will be processed. Parameters: id - The id of the requested store. siteId - The ID of the site to get the store from Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.store.modifyGETResponse

modifyGETResponse (scriptStore : Store , doc : Store ) : Status

The function is called after the request has been processed.

Parameters:: scriptStore - an instance of dw.catalog.Store; doc - the document
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.store.beforeGET

beforeGET (id : String , siteId : String ) : Status

The function is called before the request will be processed.

Parameters:: id - The id of the requested store.; siteId - The ID of the site to get the store from
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/stores/ma-bos-dt 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
Content-Length: 275

{
  "_v" : "23.2",
  "_type" : "store",
  "address1" : "333 Washington St",
  "city" : "Boston",
  "country_code" : "US",
  "email" : "[email protected]",
  "id" : "ma-bos-dt",
  "name" : "Downtown TV Shop",
  "phone" : "+1-617-695-1565",
  "postal_code" : "02108",
  "state_code" : "MA",
  "store_locator_enabled": true,
  "pos_enabled": false
}

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.