This document outlines the purpose, technology, use cases, methods, objects and examples for using the Product API.
This particular document focuses on the SOAP interface to this API.
This API provides programmatic access to the Product database, and allows for maintenance and control of the products and items within the database, as well as facilitating updates to instore and site availability.
The Products API exposes 2 primary native interfaces via .NET and SOAP.
Customised data formats, business rules and/or extended product functions are not automatically covered by the Product API.
The Products API currently supports only the iSAMS 9.1 (Scheduled) catalogue structure.
Fields are required unless otherwise stated.
Note: It is not recommended to use this API if you have customisations around product or availability 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/products.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 Products 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 / Products) 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 Product style codes present in the database.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an array of strings representing all style codes.
Lists all style codes of products linked to the specified catalogue.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| catalogue | String | Full catalogue path to return products for. |
Returns an array of strings containing the style codes of products listed in the provided catalogue path.
Returns the style codes of products created in the specified date range.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| startDate | DateTime | The start of the date range (inclusive), in UTC. |
| endDate | DateTime | The end of the date range (inclusive), in UTC. |
Returns a StringArrayApiResponse containing the style codes of all products created in the specified date range.
Returns the style codes of products modified in the specified date range.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| startDate | DateTime | The start of the date range (inclusive), in UTC. |
| endDate | DateTime | The end of the date range (inclusive), in UTC. |
Returns a StringArrayApiResponse containing the style codes of all products modified in the specified date range.
Lists all Product style codes with titles containing the search term.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| term | String | Term to search for in product titles. |
Returns an array of strings of style codes for the products whose titles contain the search term.
Retrieves a product using the style code provided.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| style | String | Style code of product to retrieve. |
Returns a ProductApiResponse containing an array (of length 1) containing the Product object for the given style code across all websites.
Users can be configured to retrieve additional image information if required.
Retrieves a product using the style code and website provided.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| style | String | Style code of product to retrieve. |
| website | Integer | Website identifier to retrieve availability for. If "0" (zero), then availability for all websites will be retrieved. |
Returns a ProductApiResponse containing an array (of length 1) containing the Product object for the given style code and website identifier.
Users can be configured to retrieve additional image information if required.
Retrieves a set of products using the style codes provided.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| styles | String[] | Style code of product to retrieve. |
Returns an ProductApiResponse containing the array of Product objects matching the given style codes across all websites.
Users can be configured to retrieve additional image information if required.
Retrieves a set of products using the style codes and website provided.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| styles | String[] | Style code of product to retrieve. |
| website | Integer | Website identifier to retrieve availability for. If "0" (zero), then availability for all websites will be retrieved. |
Returns an ProductApiResponse containing the array of Product objects matching the given style codes and website identifier.
Users can be configured to retrieve additional image information if required.
Adds or Updates a single product.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| product | Product | Product to update details for. |
Returns an ApiResponse indicating the outcome of the call.
Adds or Updates a set of products.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| product | Product[] | Array of Products to update details for. |
Returns an ApiResponse indicating the outcome of the call.
Patches (applies a partial update) to the specified fields of the provided product.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| fields | String | Comma-delimited list of supported fields that are to be patched on the matching product in this call instance.E.g. fields="Title,Manufacturer,LongDescription". Where this parameter is empty or blank, no updates will be performed. |
| product | Product | Product containing the details to patch. |
Returns an StringArrayApiResponse indicating the outcome of the call. Any records that cannot be updated, will be returned (as the Style identifier) in the Data field.
The following fields of the Product object are currently supported by this method;
Patches (applies a partial update) to the specified fields of the set of provided products.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| fields | String | Comma-delimited list of supported fields that are to be patched on the matching product in this call instance. E.g. fields="Title,Manufacturer,LongDescription". Where this parameter is empty or blank, no updates will be performed. |
| products | Product[] | Array of Products containing the details to patch. |
Returns an StringArrayApiResponse indicating the outcome of the call. Any records that cannot be updated, will be returned (as the Style identifier) in the Data field.
Deletes a product from the database.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| style | String | Style code of product to delete. |
Returns an ApiResponse indicating the outcome of the call.
Updates the availability of the provided items.
Note: This is a delta update, and updates only the products corresponding to the provided entries.If the 'Decrement In Progress From Store Availability' policy is enabled, then the current in progress orders against the imported store will be deducted from the imported quantity.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| entries | AvailabilityEntry[] | Array of AvailabilityEntries to update. |
Returns an ApiResponse indicating the outcome of the call.
Resets all availability entries with those provided.
Note: This is a full update and assumes all entries are provided. Any entries that are missing, will be treated as unavailable.If the 'Decrement In Progress From Store Availability' policy is enabled, then the current in progress orders against the imported store will be deducted from the imported quantity.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| entries | AvailabilityEntry[] | Array of AvailabilityEntries to refresh availability from. |
Returns an ApiResponse indicating the outcome of the call.
Updates the pricing of the provided items.
Note: This is a delta update, and updates only the products corresponding to the provided entries.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| entries | PricingEntry[] | Array of PricingEntries to update. |
Returns an ApiResponse indicating the outcome of the call.
updates all stock availability entries with those provided.
Note: This is a delta update, and updates only the products corresponding to the provided entries.If the 'Decrement In Progress From Store Availability' policy is enabled, then the current in progress orders against the imported store will be deducted from the imported quantity.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| entries | StockEntry[] | Array of StockEntries to refresh availability from. |
Returns an ApiResponse indicating the outcome of the call.
Resets all stock availability entries with those provided.
Note: This is a full update and assumes all entries are provided. Any entries that are missing will be treated as unavailable.If the 'Decrement In Progress From Store Availability' policy is enabled, then the current in progress orders against the imported store will be deducted from the imported quantity.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| entries | StockEntry[] | Array of StockEntries to refresh availability from. |
Returns an ApiResponse indicating the outcome of the call.
Trigger the bulk export of product data to a set of CSV files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/products/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| website | Integer | Website identifier to export products for. If "0" (zero), then all products will be exported. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
Users can be configured to retrieve additional image information if required.
A sample of a CSV-formatted product export is available here.
A sample of a CSV-formatted product export with additional image information is available here.
Trigger the bulk export of product data to a set of JSON-formatted files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/products/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| website | Integer | Website identifier to export products for. If "0" (zero), then all products will be exported. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
Users can be configured to retrieve additional image information if required.
A sample of a JSON-formatted product export is available here.
A sample of a JSON-formatted product export with additional image information is available here.
Triggers the bulk export of product data to a set of XML files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/products/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| website | Integer | Website identifier to export products for. If "0" (zero), then all products will be exported. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
Users can be configured to retrieve additional image information if required.
A sample of an XML-formatted product export is available here.
A sample of an XML-formatted product export with additional image information is available here.
Sets the main image for the identified product and item (if provided).
Note: When setting images via this method, it is recommended for performance reasons that JPEG encoded data is sent, and only at the highest resolution displayed onsite.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| style | String | Style code of the product to set the image against. |
| barcode | String (optional - may be blank) | Barcode of the related item variant to set the image against. |
| isDefault | Boolean | If true, marks the provided image as the default image for the product. |
| caption | String (optional - may be blank) | Sets the caption for this image. |
| imageData | Byte[] | Byte array containing the raw image data. |
Returns an ApiResponse indicating the outcome of the call.
Adds an alternate image for the identified product and item (if provided).
Alternate images are restricted to a certain number of available "slots", images added at higher sort orders can push other images out of the stack.
Images can be updated by setting the "order" parameter to a matching existing image.
Note: When setting images via this method, it is recommended for performance reasons that JPEG encoded data is sent, and only at the highest resolution displayed onsite.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| style | String | Style code of the product to set the image against. |
| barcode | String (optional - may be blank) | Barcode of the related item variant to set the image against. |
| order | Integer | The sort order of this image. This is adjusted internally to make room for the main image. |
| caption | String (optional - may be blank) | Sets the caption for this image. |
| imageData | Byte[] | Byte array containing the raw image data. |
Returns an ApiResponse indicating the outcome of the call.
Sets the swatch image for the identified product and item.
Note: When setting images via this method, it is recommended for performance reasons that JPEG encoded data is sent, and only at the highest resolution displayed onsite.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| style | String | Style code of the product to set the image against. |
| barcode | String | Barcode of the related item variant to set the image against. |
| caption | String (optional - may be blank) | Sets the caption for this image. |
| imageData | Byte[] | Byte array containing the raw image data. |
Returns an ApiResponse indicating the outcome of the call.
Contains basic information about the result of a method call, along with an array of Product 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 | Product[] | Array of Product objects returned for this method call. |
Represents a Product.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The unique internal ID of this product. | |
| Style | String | The style code of the product. | |
| Title | String | The title of the product. | |
| ShortDescription | String | The short description of the product (Text, HTML). | |
| LongDescription | String | The long description of the product (HTML). | |
| Supplier | String | The name of the supplier of this product. | |
| Status | Integer | Product availability status. | |
| AvailableFrom | DateTime | Date this item is available from. | |
| Price | Decimal | Purchase price of the product. | |
| Cost | Decimal | Cost price of the product. | |
| ContentLocked | Boolean | Flags whether the content is locked (for custom integration updates). | |
| ForeignIdentity | String | Unique Foreign Identity of this product. | Update sets with duplicates will have all but the last entry removed. |
| Weight | Decimal | Weight (or Freight Metric) of this product. | |
| DateCreated | DateTime | Date the product was created in the system. | |
| Manufacturer | String | Name of the manufacturer of this product. | |
| AdditionalDetails | String | String containing arbitrary additional details. | This field is ignored unless custom processing of this field is required. Expected to contain structured data (XML, JSON etc.) |
| Items | ProductItem[] | Array of items (Barcode-level) that constitute the Size/Colour variations of this product. | |
| ProductCompositeType | ProductCompositeType | Defines the make up of this product. | |
| CompositeChildren | ChildProduct[] | Array of child products for this product if it is a composite product. | If this field is null or empty then this is product is treated as a non-composite product. |
| Aspects | NameValuePair[] | Array of name-value pairs that constitute the additional search aspects/filters. | |
| ProductInformation | NameValuePair[] | Array of name-value pairs that constitute the product information items. | |
| Metadata | NameValuePair[] | Array of name-value pairs that constitute the metadata tags/values. | |
| Images | NameValuePair[] | Array of name-value pairs that contains only the main image loaded against the product and its URL. Users can be configured to retrieve additional image information if required. | |
| Catalogues | String[] | Array of catalogues to assign this product to. | |
| ProductType | String | Product Type of this product. | |
| RiskCategory | String | The risk category code for this product. |
Represents a Product Item (barcode).
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The unique internal ID of this item. | |
| Style | String | The style code of the product related to this item. | |
| Barcode | String | Barcode or APN of the item. | |
| Size | String | Size name of the item. | |
| SizeCode | String | Size code of the item. | |
| Colour | String | Name of this items' colour. | |
| ColourCode | String | Code of this items' colour. | |
| Price | Decimal | Price to charge for this item. | |
| Cost | Decimal | Cost price for this item. | |
| Quantity | Integer | Quantity available. | |
| Weight | Decimal | Weight (or Freight Metric) for this item. | |
| ForeignIdentity | String | Unique Foreign Identity of the product item. | Update sets with duplicates will have all but the last entry removed. |
| AvailableFrom | DateTime | Date this item is available from. | |
| InStock | Boolean | Flags whether or not the item is in stock. | |
| Retail | Decimal | Retail (RRP) Price for this item. | |
| AdditionalDetails | String | String containing arbitrary additional details. | This field is ignored unless custom processing of this field is required. Expected to contain structured data (XML, JSON etc.) |
| Availability | AvailabilityEntry[] | Array of availability entries. | |
| Images | NameValuePair[] | Array of name-value pairs that contains the image(s) loaded against the product item and its URL. Only populated if the user has been configured to retrieve additional image information. |
Represents an availability record.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Barcode | String | Barcode or APN of the item to set availability for. | |
| Price | Decimal | Current retail price of this item. | |
| Cost | Decimal | Current cost price of this item. | |
| SalePrice | Decimal | Current discounted price of this item. | |
| Quantity | Integer | Quantity of this item available in stock. | |
| TaxRate | Decimal | Specific sales tax rate to apply for this item. | |
| Website | Integer | Website ID. | Required for separate availability per Satellite site. If there is only one website in the group, then this can be left blank or passed as "1" (default site). |
| Branch | String | Branch code of store holding stock. | This is used only for store-level availability and does not apply to the website availability directly. |
Represents a composite child product.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Style | String | The style code of the child product. | |
| ParentStyle | String | The style code of the parent product. | |
| Type | ComponentType | The ComponentType of this component of the composite product. | |
| Quantity | Integer | Quantity of this item that makes up the composite. | If the quantity is not included for optional components the quantity purchased with the composite can be specified by the buyer. If the Type is Included or Required a quantity must be specified. |
| Price | Decimal | The price of this component when purchased as part of the composite product. | If not specified the component's individual sale price will be added to the total price of the composite. If the Type is Included the Price property is ignored. |
| Order | Integer | The order that the child products should be displayed in. |
Specifies the behaviour of a component in a composite product.
| Name | Value | Description | Notes |
|---|---|---|---|
| Required | 3 | This component is required to make up the composite product. | |
| Optional | 2 | This component can be optionally purchased with the composite product. | |
| Included | 1 | This component is included in the price of the composite product. | Obsolete: This behaviour can be obtained by setting ChildProduct.ComponentType to Required and ChildProduct.Price to 0. |
Defines the make up of a Product.
| Name | Value | Description |
|---|---|---|
| Product | 1 | The Product is a standard product, it may have additional optional components that can be purchased with the Product for an additional price. |
| Group | 2 | The Product defines a group of optional components that are displayed together but purchased separately. |
| Set | 4 | The Product defines set of included components that can be purchased together for a price of the Set.
The Set may have additional optional components that can be purchased with the Set for an additional price. |
Represents a pricing record.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Barcode | String | Barcode or APN of the item to set pricing for. | |
| Price | Decimal | Current retail price of this item. | |
| Cost | Decimal | Current cost price of this item. | |
| SalePrice | Decimal | Current discounted price of this item. | |
| TaxRate | Decimal | Specific sales tax rate to apply for this item. | |
| Website | Integer | Website ID. | Required for separate pricing per Satellite site. If there is only one website in the group, then this can be left blank or passed as "1" (default site). |
Represents a stock availability record.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Barcode | String | Barcode or APN of the item to set stock availability for. | |
| Quantity | Integer | Quantity of this item available in stock. | |
| Website | Integer | Website ID. | Required for separate pricing per Satellite site. If there is only one website in the group, then this can be left blank or passed as "1" (default site). |
| Branch | String | Branch code of store holding stock. | This is used only for store-level availability and does not apply to the website availability directly. |
| SystemFlag | int | Platform stock indicator. | Reserved for future use |
| CustomFlag | int | Custom stock indicator to support custom stock rules. | Reserved for future use |
| Comment | String | Free text field. | Reserved for future use |
The Products API returns standard API response codes.
| Status | Description | Notes |
|---|---|---|
| 0 | Available on Site and for Sale | |
| 1 | Not Available on Site and Not for Sale | |
| 2 | Available on Site and Not for Sale | |
| 3 | Not Available on Site and for Sale | |
| 4 | Available on Site and MOTO Sale Only |