introducing the inventory inquiry api (rest) shopatron ... · parameter required data type...

Introducing the Inventory Inquiry API (REST)

ADD TO CART XML API GUIDE 11/22/13 | PAGE 1

SHOPATRON

Inventory Inquiry API Guide Version 3 REST

Revision/

Version

Number

Summary of Modifications Date Author/Writer Subject Matter

Expert(s)

3.0 Initial release for this version. November 22, 2013 Michael Lujan Dave Miller,

James Elliot

Copyright © 2013 Shopatron, Inc.

Shopatron North America

Shopatron, Inc.

P.O. Box 5351

San Luis Obispo, CA, 93403

Shopatron Europe

Shopatron UK, Ltd.

Newport House

19-21 Newport Street

Old Town, Swindon SN1 3DX

Contents

Introducing the Inventory Inquiry API (REST) .......................................................... 4

Getting Started ............................................................................................................ 4

Before you begin ................................................................................................................ 4

Obtaining API access ........................................................................................................ 4

System requirements ......................................................................................................... 4

Inventory Inquiry API Call ........................................................................................... 4

getInventory ........................................................................................................................ 5

Resource information......................................................................................................... 5

Request data parameters .................................................................................................. 5

Request header ................................................................................................................. 7

Example request ................................................................................................................ 7

Response data elements ................................................................................................... 9

Success response ........................................................................................................... 10

Handling Errors ......................................................................................................... 11

Country Codes .......................................................................................................... 12

HTTP Error Codes ..................................................................................................... 13


INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 4


Shopatron's Inventory Inquiry API allows you to share your real-time inventory information among

multiple fulfillment locations.

REpresentational State Transfer (REST) is a style of software architecture for distributed systems such

as the World Wide Web. REST has emerged as a predominant Web service design model.

Getting Started

NOTE: Shopatron usually recommends the Inventory Inquiry API to developers who have experience with REST as well as to those who have a dedicated IT staff of capable programmers and a web-capable database for product and order data storage.

Before you begin

Obtaining API access

Before you can use the Inventory Inquiry API functions described in this guide, you will need to contact

Shopatron Merchant Support at (877) 715-7467 or send email to [email protected] to obtain the

information to configure your account.

System requirements

To use the Inventory Inquiry API, you need a client with Internet access that runs your own REST client

to send data to the Shopatron server.

NOTE:

Shopatron reserves the right to disallow the use of this API if the user violates Shopatron policies. Before we take this action, we attempt to contact the user. Additionally, we reserve the right to augment or modify this API at any time. This includes changing the number of, name of, and placement of data attributes and the queue schedule by which this API operates. While we will make every effort to provide regression support for older versions, you should prepare your application to anticipate updates. We do not recommend hard-coding the attribute placement by number, as the order of the attributes may change.

Inventory Inquiry API Call

This document contains information about the Inventory Inquiry (REST) Web service getInventory

call.

mailto:[email protected]



getInventory

Resource information

Call Syntax/URL https://api.shopatron.com/coex/services/rest/client/v3/

inventory/post_query

Synopsys Returns an array of inventory items given a set of criteria.

Version 3

HTTP Method POST

Supported Formats JSON

Request data parameters

Refer to this table for details for defining request data parameters.

Parameter Required Data Type Description

manufacturerID Yes Integer Shopatron manufacturer ID.

catalogID Yes Integer The Shopatron-assigned catalog ID.

type Yes Enumeration An enumeration of strings for the type of

request being made:

ANY - fulfillment locations that have partial

quantities of line items in stock

ALL - fulfillment locations that have all

complete line items in stock

PARTIAL - fulfillment locations that have

some complete line items in stock

ALL_STORES – all fulfillment locations

that have all complete line items in stock

postalCode No String All locations with the specified postal code.

latitude Yes, but only

if longitude is

in the

request

Number The latitude coordinates for the location.




longitude Yes, but only

if latitude is

in the

request

Number The longitude coordinates for the location.

countryCode No String All locations with the specified country code.

radius No Number The radius from the specified point within

which to search. The point is specified by

latitude/longitude or zip code.

unit No Enumeration The unit in which the radius will be

interpreted:

M – Miles

KM - Kilometers

limit No Integer The maximum number of results to return.

ignoreSafetyStock No Boolean Should the results ignore safety stock?

includeNegativeInventory No Boolean Should the results include negative

inventory?

STSEnabled No Boolean Does the location have STS enabled?

STHEnabled Boolean Does the location have STH enabled?

ISPUEnabled No Boolean Does the location have ISPU enabled?

locationNames No String Location name when coupled with

fulfillerID uniquely identifies a

Fulfillment Location.

items Yes Array of

objects

Each object contains these properties:

partNumber, UPC, SKU, and quantity.

partNumber Conditional String An item property. The part number for the

item, as assigned by the manufacturer.

UPC Conditional String An item property. The merchant's Universal

Product Code (UPC) for this item.

SKU Conditional String An item property. Fulfillment Location-

specific stock keeping unit (SKU), if available.




quantity Yes, with at

least one of

the other

items

properties

Integer An item property. The number of units of this

item the consumer wants.

Request header

API-Key : <apikey>

Content-Type: application/json

Example request

{

"title": "Get Inventory Query",

"type": "object",

"properties": {

"manufacturerID": {

"title": "Manufacturer Identifier",

"type": "integer",

"minimum": 0

},

"catalogID": {

"title": "Catalog Identifier",

"type": "integer",

"minimum": 0

},

"type": {

"title": "Request Type",

"enum": [

"ANY",

"ALL",

"PARTIAL",

"ALL_STORES"

]

},

"postalCode": {

"title": "Postal Code",

"type": "string"

},

"latitude": {

"title": "Latitude",

"type": "number"

},

"longitude": {

"title": "Longitude",

"type": "number"

},

"countryCode": {

"title": "Country Code",

"type": "string"

},

"radius": {

"title": "Radius from lat/lon or zip to search within",

"type": "number"

},



"unit": {

"title": "Radius from lat/lon or zip to search within",

"enum": [

"M",

"KM"

]

},

"limit": {

"title": "The maximum number of results to return",

"type": "integer",

"minimum": 1

},

"ignoreSafetyStock": {

"title": "Should the results ignore safety stock",

"type": "boolean"

},

"includeNegativeInventory": {

"title": "Should the results include inventory less than 0",

"type": "boolean"

},

"STSEnabled": {

"title": "Does the location have STSEnabled",

"type": "boolean"

},

"STHEnabled": {

"title": "Does the location have STHEnabled",

"type": "boolean"

},

"ISPUEnabled": {

"title": "Does the location have ISPUEnabled",

"type": "boolean"

},

"locationNames": {

"title": "Fulfiller Location Names",

"type": "array",

"items": {

"title": "Location Name",

"type": "string"

}

},

"items": {

"title": "Product Information to query for",

"type": "array",

"items": {

"type": "object",

"properties": {

"partNumber": {

"title": "Part Number",

"type": "string"

},

"UPC": {

"title": "Universal Product Code",

"type": "string"

},

"SKU": {

"title": "Stock Keeping Unit",

"type": "string"

},

"quantity": {

"title": "Number being requested",

"type": "integer",

"minimum": 0



}

}

}

}

},

"additionalProperties": false,

"required": [

"manufacturerID",

"catalogID"

]

}

Response data elements

Refer to this table for details for the data elements returned.

Element Data Type Description

locationName String Location name when coupled with fulfillerID uniquely

identifies a Fulfillment Location.

ManufacturerID Integer Shopatron manufacturer ID.

CatalogID Integer The Shopatron-assigned catalog ID.

OnHand Integer Number of on-hand inventory items.

Available Integer Number of inventory items available at the physical Fulfillment

Location which can be ordered.

PartNumber String Vendor-specific part number.

UPC String Vendor-specific UPC.

SKU String Fulfillment Location-specific UPC, if available.

LTD Double "Lifetime To Date." This is a flexible sales metric that may be

defined and interpreted any way the manufacturer prefers; for

example, the sales velocity metric (sales / days in operation).

Floor Integer "Floor" is a term used to describe a flexible threshold. With

respect to the example for 'safety stock' below, this threshold

can be, for example, the number of items in stock a

manufacturer can drop down to before some sort of email

notification is sent out to someone (as opposed to Safety

Stock, below).



Element Data Type Description

SafetyStock Integer "Safety stock" is a term used to describe a flexible threshold.

With respect to the example of 'floor' above, this threshold can

be, for example, the number of items in stock that a

manufacturer can drop down to before it stops fulfilling orders

altogether.

Distance Number Distance from the location from which the query is made.

STHEnabled Boolean Whether or not the store has enabled Ship to Home.

RestockEnabled Boolean Whether or not the store has enabled restock.

PickupEnabled Boolean Whether or not the store has enabled pickup.

US String The country code for the location

STHRank Integer Ship to Home Ranking.

Restock Integer Restock Ranking.

Success response

{

"title": "Get Inventory Response",

"type": "array",

"items" : {

"type": "object",

"properties": {

"locationName" : {

"title": "The Name of the Location",

"type": "string"

},

"ManufacturerID": {

"title": "Manufacturer Identifier",

"type": "integer",

"minimum": 0

},

"CatalogID": {

"title": "Catalog Identifier",

"type": "integer",

"minimum": 0

},

"OnHand": {

"title": "Number of Items On Hand",

"type": "integer",

},

"Available": {

"title": "Number of Items Available",

"type": "integer",

},

"PartNumber": {

"title": "Part Number",

"type": "string"

Handling Errors


},

"UPC": {

"title": "Universal Product Code",

"type": "string"

},

"SKU": {

"title": "Stock Keeping Unit",

"type": "string"

},

"LTD": {

"title": "Life to Date",

"type": "integer",

},

"Floor": {

"title": "Number of Items on the Store Floor",

"type": "integer",

},

"SafetyStock": {

"title": "Number of Items Needed at the store in case

somebody wants to buy it",

"type": "integer",

},

"Distance": {

"title": "Distance from the location queried for",

"type": "number",

},

"STHEnabled": {

"title": "Whether the store has Ship to Home enabled",

"type": "boolean",

},

"RestockEnabled": {

"title": "Whether the store has restock enabled",

"type": "boolean",

},

"PickupEnabled": {

"title": "Whether the store has pickup enabled",

"type": "boolean",

},

"US": {

"title": "The country code for the location",

"type": "string"

},

"STHRank": {

"title": "Ship to Home Ranking",

"type": "integer",

},

"Restock": {

"title": "Restock Ranking",

"type": "integer",

}

}

}

}

Handling Errors

If you receive an error response fault code when you send the order information to Shopatron, follow

these steps:

Country Codes


1. Record the outgoing package and the associated fault code response from Shopatron.

2. Test for connectivity to the server.

3. Hold the REST package for future transmission to Shopatron's servers.

4. Send an email to Shopatron Merchant Support at [email protected]; include the time and date

of the failed transmission.

5. When Shopatron support staff contacts you, resend the failed attempts.

Country Codes

Refer to these codes for parameter elements pertaining to country codes.

Country 2-Character Country

Code


Code

Anguilla AI Ireland IE

Antigua & Barbuda AG Italy IT

Argentina AR Japan JP

Aruba AW Korea, South KR

Australia AU Kuwait KW

Austria AT Liechtenstein LI

Bahamas BS Luxembourg LU

Barbados BB Macao MO

Belgium BE Malaysia MY

Belize BZ Martinique MQ

Bermuda BM Netherlands NL

Bhutan BT Netherlands Antilles AN

Brazil BR New Caledonia NC

British Virgin Islands VG New Zealand NZ

Canada CA Norway NO

Chile CL Portugal PT

HTTP Error Codes



Code


Code

China CN Reunion Island RE

Costa Rica CR Saint Lucia LC

Czech Republic CZ Saint Pierre & Miquilon PM

Denmark DK San Marino SM

Egypt EG Singapore SG

Fiji FJ Solomon Islands SB

Finland FI South Africa ZA

France FR Spain ES

French Polynesia PF Sweden SE

Germany DE Switzerland CH

Great Britain GB Taiwan TW

Greece GR Thailand TH

Greenland GL Trinidad & Tobago TT

Guadeloupe GP United Arab Emirates AE

Guam GU United Kingdom GB

Hong Kong HK United States of

America

US

Iceland IS Vatican City VA

India IN

HTTP Error Codes

Code Description

400 Bad Request. The request could not be understood by the server due to malformed syntax.

The client should not repeat the request without modifications.

401 Unauthorized. The request requires user authentication. The response must include a

WWW-Authenticate header field containing a challenge applicable to the

requested resource. The client may repeat the request with a suitable

Authorization header field. If the request already included Authorization

HTTP Error Codes


Code Description

credentials, then the 401 response indicates that authorization has been

refused for those credentials. If the 401 response contains the same

challenge as the prior response, and the user agent has already attempted

authentication at least once, then the user should be presented the entity that

was given in the response, since that entity might include relevant diagnostic

information. HTTP access authentication is explained in HTTP Authentication:

Basic and Digest Access Authentication.

403 Forbidden. The server understood the request, but is refusing to fulfill it. Authorization will

not help and the request should not be repeated. If the request method was

not Head, and the server wishes to make public why the request has not been

fulfilled, it should describe the reason for the refusal in the entity. If the server

does not wish to make this information available to the client, the status code

404 (Not Found) can be used instead.

404 Not Found. The server has not found anything matching the Request-URI. No indication is

given of whether the condition is temporary or permanent. The 410 (Gone)

status code should be used if the server knows, through some internally

configurable mechanism, that an old resource is permanently unavailable and

has no forwarding address. This status code is commonly used when the

server does not wish to reveal exactly why the request has been refused, or

when no other response is applicable.

409 Conflict. The request could not be completed due to a conflict with the current state of

the resource. This code is only allowed in situations where it is expected that

the user might be able to resolve the conflict and resubmit the request. The

response body should include enough information for the user to recognize

the source of the conflict. Ideally, the response entity would include enough

information for the user or user agent to fix the problem; however, that might

not be possible and is not required.

Conflicts are most likely to occur in response to a PUT request. For example,

if versioning were being used and the entity being PUT included changes to a

resource which conflict with those made by an earlier (third-party) request, the

server might use the 409 response to indicate that it can't complete the

request. In this case, the response entity would likely contain a list of the

differences between the two versions in a format defined by the response

Content-Type.

413 Request Entity Too Large. The server is refusing to process a request because the request entity is

larger than the server is willing or able to process. The server may close the

connection to prevent the client from continuing the request.

If the condition is temporary, the server should include a Retry- After header

field to indicate that it is temporary as well as after what time the client MAY

try again.

500 Internal Server Error. The server encountered an unexpected condition which prevented it from

fulfilling the request.

HTTP Error Codes


introducing the inventory inquiry api (rest) shopatron ... · parameter required data type...

Documents