This document outlines the purpose, technology, use cases, methods, objects and examples for using the Stores API.
This particular document focuses on the SOAP interface to this API.
This API provides programmatic access to the Store database, and allows for maintenance and control of the stores within the database.
The Stores API exposes 2 primary native interfaces via .NET and SOAP.
Customised data formats, business rules and/or extended store functions are not automatically covered by the Stores API.
Note: It is not recommended to use this API if you have customisations around store integrations without first understanding how the use of this API may impact these.
Full documentation for this interface is available in the API Reference.
This section documents the SOAP interface to the API.
The SOAP API endpoint for any site is located at https://[siteurl]/global/api/stores.asmx
This endpoint is enabled for access via SOAP as well as HTTP GET & POST. The Service Description is also available directly via this endpoint.
Note: For systems with satellite sites, the API will be available only under the primary site URL.
The Stores API via SOAP uses the Permissions System to allow and deny access to certain users. Use of the API requires a user to be granted the various actions (under iSAMS / API / Stores) to be able to authenticate, and perform the various actions available under this API.
Error handling is primarily left to the caller, however any methods that return an ApiResponse object will provide additional details that can be used to assist when debugging problems.
Where a "Call Identifier" is returned in the Message field of the ApiResponse, then a full exception trace will be available from [website url]/logs/api/{Call Identifier}.txt
The available methods are listed below, and link to the relevant details for which arguments are required, and the responses each method provides;
The available objects are listed below, and link to the relevant details for each;
See Authenticate.
Lists all unique store countries.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an array of strings containing the all unique countries listed against stores.
Lists all countries with a name matching the provided search term.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| searchTerm | String | Search term to search for among store countries. |
Returns an array of strings containing the all unique countries matching the search term.
Lists all Areas against stores in the database.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an array of Area objects containing the all unique areas among stores in the database.
Lists all Areas against stores in the database within a particular country.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| country | String | The country within which to list areas. |
Returns an array of Area objects containing the all unique areas among stores in the database that are within a country.
Lists all Areas against stores in the database with the provided name.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| areaName | String | The name to list matching areas for. |
Returns an array of Area objects with a name matching the requested name.
Adds or updates a store in the database.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| newStore | Store | The store to add or update. |
Returns a ApiResponse indicating the outcome of the call.
Adds or updates a store in the database.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| updatedStore | Store | The store to add or update. |
Returns a ApiResponse indicating the outcome of the call.
Adds or updates multiple stores in the database.
Note: This is a delta update, and updates only the stores corresponding to the provided entries.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| updatedStores | Store[] | The stores to add or update. |
Returns a ApiResponse indicating the outcome of the call.
Deletes a store in the database.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| ID | int | The ID of the store to delete. |
Returns a ApiResponse indicating the outcome of the call.
Searches for stores based on a provided search term.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| searchTerm | String | The search term to search for. |
Returns a StoresApiResponse containing the located stores.
Retrieves a store matching the provided store ID.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| ID | String | The ID of the store to retrieve. |
Returns a StoresApiResponse containing the located store.
Retrieves a store with the provided branch code.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| branchCode | String | The branch code of the store to retrieve. |
Returns a StoresApiResponse containing the located store.
Lists all stores present in the database.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns a StoresApiResponse containing the list of stores.
Lists all stores present in the database belonging to a particular satellite.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| wsID | int | ID of the satellite. |
Returns a StoresApiResponse containing the list of stores.
Lists all stores present in the database within a particular country.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| country | String | The country to search for stores in. |
Returns a StoresApiResponse containing the list of stores.
Lists all stores present in the database within a particular area.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| area | Area | The area to search for stores in. |
Returns a StoresApiResponse containing the list of stores.
Lists all stores located within a particular radius from a postcode.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| country | String | The country to search for stores in. |
| postcode | String | The postcode to search for stores near to. |
| radius | int | The radius (in metres) within which to find stores. |
Returns a StoresApiResponse containing the list of stores.
Lists all stores located within a particular radius from a geographical location.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| latitude | int | The latitude of the geographical location. |
| longitude | int | The longitude of the geographical location. |
| radius | int | The radius (in metres) within which to find stores. |
Returns a StoresApiResponse containing the list of stores.
Triggers the bulk export of store data to a set of XML files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/stores/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an XML-formatted store export is available here.
Triggers the bulk export of store data belonging to a satellite to a set of XML files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/stores/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| website | int | The website ID of the satellite. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an XML-formatted store export is available here.
Triggers the bulk export of store data to a set of Csv files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/stores/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an Csv-formatted store export is available here.
Triggers the bulk export of store data belonging to a satellite to a set of Csv files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/stores/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| website | int | The website ID of the satellite. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an Csv-formatted store export is available here.
Triggers the bulk export of store data to a set of JSON-formatted files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/stores/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an JSON-formatted store export is available here.
Triggers the bulk export of store data belonging to a satellite to a set of JSON-formatted files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/stores/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| website | int | The website ID of the satellite. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an JSON-formatted store export is available here.
Contains basic information about the result of a method call, along with an array of Store objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | Store[] | Array of Store objects returned for this method call. |
Contains basic information about the result of a method call, along with an array of Area objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | Area[] | Array of Area objects returned for this method call. |
Represents a Store.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | int | The ID of the store. | |
| Active | bool | The store active status. | |
| BranchCode | string | The store branch code. | |
| Name | string | The store name. | |
| Manager | string | The store manager. | |
| Area | Area | The store area. | |
| Latitude | string | The store latitude position. | |
| Longitude | string | The store longitude position. | |
| Address | string | The store address. | |
| AddressDetails | AddressDetails | The store address details. | |
| Details | string | The store details. | |
| Type | string | The store type. | |
| string | The store email. | ||
| StoreLocator | bool | The store locator status. | |
| StoreAvailability | bool | The store availability status. | |
| ClickAndCollect | bool | The store is avilable for click and collect status. |
Represents an Area.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Name | string | The area name. | |
| Country | string | The area country. |
Represents Address of the store.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Company | string | Company. | |
| Street | string | Street. | |
| Suburb | string | Suburb. | |
| City | string | City. | |
| State | string | State. | |
| Postcode | string | Postcode. | |
| ContactPhone | string | Contact phone number. |
The Stores API returns standard API response codes.