Salesforce B2C Commerce 23.6 > 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.

Get nearest 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:

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 Arguments 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

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

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 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

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
}

© Copyright 2000-2023, Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners.

 Show URL Submit FeedbackPrivacy Policy
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.
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.