Stores Resource (Shop API 16.9)

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

Sample

REQUEST:
GET /dw/shop/v16_9/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" : "16.9",
  "_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,
    "demandware_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,
    "demandware_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,
    "demandware_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,
    "demandware_pos_enabled": false
  } ],
  "next" : "http://example.com/dw/shop/v16_9/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/v16_9/stores/({id},...,{id})

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

StoreResult

Path Parameters

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.store.afterGET

afterGET (doc : Document) : Status

The function is called after the request has been processed.

Parameters:
doc - the document
Returns:
  • Status.OK for success.
  • Status.ERROR in case something went wrong.

Sample

REQUEST:
GET /dw/shop/v16_9/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":"16.9",
  "_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,
      "demandware_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,
      "demandware_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/v16_9/stores/{id}

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

Store

Path Parameters

Parameter Type Description Constraints
id String The id of the requested store. maxLength=256

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

Sample

REQUEST:
GET /dw/shop/v16_9/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
x-dw-version-status: beta
Content-Length: 275

{
  "_v" : "16.9",
  "_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,
  "demandware_pos_enabled": false
}

© Copyright 2000-2020, salesforce.com inc. All rights reserved. Various trademarks held by their respective owners.

 Show URL Submit FeedbackPrivacy Policy
OCAPI obsolete versions 13.x and 14.x will be end of life in 2020 and versions 15.x and 16.x in 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.