Product Data 1.0.0

PROMOTIONAL PRODUCTS DATA INTERFACE SPECIFICATION FOR WEB SERVICES

Product Data 1.0.0

PromoStandards Logo

Version: 1.0.0

Date: 2016-06-08

Document Change Log

VersionDateReason for ChangeAuthor
1.0.02016-06-08Initial ReleaseTim Nale, Director IT BIC Graphic NA

Contributors

The following have contributed to the creation of this specification:

Design : Tim Nale, Director of IT, BIC Graphic

Contributors :

  • Paul Fleischman, Technical Lead, PCNA
  • Jon Norris, VP of Operations, Starline

Product Data

There will be four functions available as part of this web service.

getProduct()

This function will provide the detail product data based on a specific ProductId or any additional optional subset filtering provided at the request.

Request: GetProductRequest

FieldDescriptionData TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}64 STRINGTRUE
idThe customer Id or any other agreed upon Id.64 STRINGTRUE
passwordThe password associated with the Id64 STRINGFALSE
localizationCountryISO 3166-1 Alpha 2 code for Country
Example:
CA=Canada
US=United States
2 STRINGTRUE
localizationLanguageISO 639-1 Alpha 2 code for Language
Example:
en = English
fr = French
2 STRINGTRUE
productIdItem's ID64 STRINGTRUE
partIdThe Supplier specific PartId; commonly referred to as a sku64 STRINGFALSE
colorNameA specific part color for this product64 STRINGFALSE
ApparelSizeArrayUsed for returning specific apparel sizes. Array of ApparelSize objectsARRAYFALSE

Reply: GetProductResponse

FieldDescriptionData TypeRequired?
ProductProduct InformationOBJECTFALSE
ErrorMessageResponse for any error requiring notification to requestorOBJECTFALSE

Product Object

FieldDescriptionData TypeRequired?
productIdThe associated product.64 STRINGTRUE
productNameThe Supplier name for the product256 STRINGTRUE
descriptionBasic product description or bulleted list of descriptions.2048 STRING ARRAYTRUE
ProductMarketingPointArrayMarketing points type and content. An array of MarketingPoint objects.OBJECT ARRAYFALSE
ProductKeywordArrayArray of keywords often used in searching for this product. An array of ProductKeyword objects.OBJECT ARRAYFALSE
productBrandThe specific product brand64 STRINGFALSE
exportProduct status for exportNILLABLE BOOLEANTRUE
ProductCategoryArrayThe product's categorization array. An array of ProductCategory objects.OBJECT ARRAYFALSE
RelatedProductArrayProducts related to the quested product as Substitutable, CompanionSell, or Common Grouping (Family). An array of RelatedProduct objects.OBJECT ARRAYFALSE
ProductPartArrayAll part specific product data. An array of ProductPart objects.OBJECT ARRAYTRUE
lastChangeDateThe date time stamp of the most recent change to this data in ISO 8601 formatISO 8601 DATETRUE
creationDateThe date time stamp when this products data initially became available in ISO 8601 formatISO 8601 DATETRUE
endDateThe Date this Product expires from Supplier availability in ISO 8601 formatISO 8601 DATEFALSE
effectiveDateThe Date this Product initially becomes available from the Supplier in ISO 8601 formatISO 8601 DATEFALSE
isCautionCautionary status to review for specific warnings about using product dataNILLABLE BOOLEANTRUE
cautionCommentProduct cautionary comments1024 STRINGFALSE
isCloseoutIndicates if the product is a closeoutNILLABLE BOOLEANTRUE
lineNameLine Name / Division to which this product belongs64 STRINGFALSE

ProductCategory Object

FieldDescriptionData TypeRequired?
categoryProduct category256 STRINGTRUE
subCategoryProduct subcategory256 STRINGFALSE

ProductMarketingPoint Object

FieldDescriptionData TypeRequired?
pointTypeBasic category or type of marketing point being made. e.g. Highlights, Size, Safety64 STRINGFALSE
pointCopyMarketing bullet or point copy1024 STRINGTRUE

ProductKeyword Object

FieldDescriptionData TypeRequired?
keywordA product keyword commonly utilized for search or other functions64 STRINGTRUE

RelatedProduct Object

FieldDescriptionData TypeRequired?
relationTypeThe relationship type between two products64 STRINGTRUE
productIdProduct Id64 STRINGTRUE
partIdPart specific Id64 STRINGFALSE

ProductPart Object

FieldDescriptionData TypeRequired?
partIdThe part Id64 STRINGTRUE
descriptionDescription2048 STRING ARRAYFALSE
countryOfOriginCountry of Origin
ISO 3166-1 Alpha 2 code for Country
Example: CA=Canada;
US=United States
2 STRINGFALSE
ColorArrayInformation about the part colorsOBJECT ARRAYFALSE
primaryMaterialPrimary material of construction64 STRINGFALSE
SpecificationArraySpecificationsOBJECT ARRAYFALSE
shapeGeneral shape64 STRINGFALSE
ApparelSizeUsed to describe an apparel sizeOBJECTFALSE
DimensionPhysical dimensions and weightOBJECTFALSE
leadTimeLead time in daysINTFALSE
unspscUnited Nations Standard Products and Services Code (UNSPSC)8 STRINGFALSE
gtinGlobal Trade Item Number (GTIN)14 STRINGFALSE
isRushServiceRush serviceNILLABLE BOOLEANTRUE
ProductPackagingArrayPackaging option details; e.g. Gift Box, Cello Pack, Sleeve. An array of ProductPackaging objects.OBJECT ARRAYFALSE
ShippingPackageArrayShipping package option details for the partPackaging Default package type; e.g. Carton, Box, Pallet. An array of ShippingPackage objects.OBJECT ARRAYFALSE
endDateThe date this part expires from supplier availability in ISO 8601 formatISO 8601 DATEFALSE
effectiveDateThe Date this Part initially becomes available from the Supplier in ISO 8601 formatISO 8601 DATEFALSE
isCloseoutIndicates if a closeoutNILLABLE BOOLEANTRUE
isCautionCautionary status to review for specific warnings about using product dataNILLABLE BOOLEANTRUE
cautionCommentCautionary comments1024 STRINGFALSE
nmfcCodeNational Motor Freight Classification CodeDECIMALFALSE
nmfcDescriptionNational Motor Freight Classification Description1024 STRINGFALSE
nmfcNumberNational Motor Freight Classification Number64 STRINGFALSE
isOnDemandManufactured on demand / Made to orderNILLABLE BOOLEANTRUE
isHazmatContains hazardous material. A nil value indicates this it is unknown or the data is not available by the supplier.NILLABLE BOOLEANTRUE

Color Object

FieldDescriptionData TypeRequired?
colorNameSupplier specific color name. Go to market color64 STRINGTRUE
hexThe HEX code representation. This is not a supplement for product color but data used for generating web user interfaces.64 STRINGFALSE
approximatePmsThe PMS code representation. This is not a supplement for product color.64 STRINGFALSE

Specification Object

FieldDescriptionData TypeRequired?
specificationTypeThe type of specification64 STRING FACITTRUE
specificationUomSpecification unit of measure64 STRINGTRUE
measurementValueSpecification Measurement Value64 STRINGTRUE

ApparelSize Object

FieldDescriptionData TypeRequired?
apparelStyleApparel style64 STRING FACITTRUE
labelSizeThe apparel items tagged size. e.g. XS, S, M, L, etc.6 STRING FACITTRUE
customSizeUsed to communicate custom size when labelSize is CUSTOM.64 STRINGFALSE

Dimension Object

FieldDescriptionData TypeRequired?
dimensionUomThe dimensional unit of measure2 STRING FACITTRUE
depthThe depth/length of the part using the unit of measure specified in dimensionUomDECIMALFALSE
heightThe height of the part using the unit of measure specified in dimensionUomDECIMALFALSE
widthThe width of the part using the unit of measure specified in dimensionUomDECIMALFALSE
weightUomThe weight unit of measure for the part2 STRING FACITTRUE
weightThe weight of the part using the unit of measure specified in dimensionUomDECIMALFALSE

ProductPackaging Object

FieldDescriptionData TypeRequired?
defaultBoolean flag identifying the single default packaging for this packageBOOLEANTRUE
packageTypeThe packaging specific type for this partId e.g. Gift Box, Cello Pack, Sleeve256 STRINGTRUE
descriptionThe Packaging specific description2048 STRINGFALSE
quantityThe partId unit Quantity included within this specific Packaging OptionDECIMALTRUE
dimensionUomThe unit of measure for the package2 STRING FACITTRUE
depthThe depth/length of the package in the dimensionUom unit of measureDECIMALFALSE
heightThe height of the package in the dimensionUom unit of measureDECIMALFALSE
widthThe width of the package in the dimensionUom unit of measureDECIMALFALSE
weightUomThe weight unit of measure for the packageType2 STRING FACITTRUE
weightThe weight of the specific packageTypeDECIMALFALSE

ShippingPackage Object

FieldDescriptionData TypeRequired?
packageTypeThe shipping package specific type for this shipping package e.g. Box, Carton, etc.256 STRINGTRUE
descriptionThe shipping package specific description2048 STRINGFALSE
quantityThe partId unit quantity included within this specific shipping packaging optionDECIMALTRUE
dimensionUomThe weight unit of measure for the packageType2 STRING FACITTRUE
depthThe depth/length of the shipping package in the dimensionUom unit of measureDECIMALFALSE
heightThe height of the shipping package in the dimensionUom unit of measureDECIMALFALSE
widthThe width of the shipping package in the dimensionUom unit of measureDECIMALFALSE
weightUomThe weight unit of measure for the packageType2 FACIT STRINGTRUE
weightThe weight of the specific packageTypeDECIMALFALSE

getProductDateModified()

This function will provide the list of Product Ids and optional Part Ids for all items which have changed since the date supplied in the request.

Request: GetProductDateModifiedRequest

FieldDescriptionData TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}64 STRINGTRUE
idThe customer Id or any other agreed upon Id.64 STRINGTRUE
passwordThe password associated with the Id64 STRINGFALSE
changeTimeStampBeginning date time since last change in UTCISO 8601 DATETRUE

Reply: GetProductDateModifiedResponse

FieldDescriptionData TypeRequired?
productChangeArrayArray listing of all Product and Part specific Ids which have changed since the reference date requested (lastChangeDate). An array of ProductChange objects.OBJECT ARRAYTRUE
ErrorMessageResponse for any error requiring notification to requestorOBJECTFALSE

ProductChange Object

FieldDescriptionData TypeRequired?
productIdThe associated product64 STRINGTRUE
partIdThe associated part64 STRINGFALSE

getProductCloseOut()

This function will provide a list of Product Ids and optional Part Ids for all items which currently have an isCloseOut value of TRUE.

Request: GetProductCloseOutRequest

FieldDescriptionData TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}64 STRINGTRUE
idThe customer Id or any other agreed upon Id.64 STRINGTRUE
passwordThe password associated with the Id64 STRINGFALSE

Reply: GetProductCloseOutResponse

FieldDescriptionData TypeRequired?
ProductCloseOutArrayAll product and part specific Ids which are on closeout. An array of ProductCloseOut objects.OBJECT ARRAYTRUE
ErrorMessageResponse for any error requiring notification to requestorOBJECTFALSE

ProductCloseOut Object

FieldDescriptionData TypeRequired?
productIdThe associated product64 STRINGTRUE
partIdThe associated part64 STRINGFALSE

getProductSellable()

This function will provide a list of Product Ids and optional Part Ids along with their status of available to sell (Sellable TRUE or FALSE).

Request: GetProductSellableRequest

FieldDescriptionData TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}64 STRINGTRUE
idThe customer Id or any other agreed upon Id.64 STRINGTRUE
passwordThe password associated with the Id64 STRINGFALSE
productIdThe associated product64 STRINGFALSE
partIdThe associated part64 STRINGFALSE
isSellableIndicates if sellableBOOLEANTRUE

Reply: GetProductSellableResponse

FieldDescriptionData TypeRequired?
ProductSellableArrayArray listing of all product and part specific Ids along with sellable status. An array of ProductSellable objects.OBJECT ARRAYTRUE
ErrorMessageResponse for any error requiring notification to requestorOBJECTFALSE

ProductSellable Object

FieldDescriptionData TypeRequired?
productIdThe associated product64 STRINGTRUE
partIdThe associated part64 STRINGFALSE

Enumerated Type Restrictions

wsVersionThe Standard Version of the Web Service being referenced64 STRING FACET1.0.0
dimensionUomThe dimensional unit of measure64 STRING FACETMM (Millimeter)
CM (Centimeter)
MR (Meter)
IN (Inch)
FT (Feet)
YD (Yards)
weightUomThe weight unit of measure2 STRING FACETME (Milligram)
KG (Kilogram)
OZ (Ounce)
LB (Pound)
relationTypeThe relationship type between the two products64 STRING FACETSubstitute
Companion Sell
Common Grouping
specificationTypeList of possible values. The type of specification.64 STRING FACETLength
Thickness
Radius
Volume
Capacity
Memory
Data Ports
Capacitance
Voltage
Point Size
Sheet Size
Sheet Count
Pockets
Inseam
Bust
Chest
Waist
Hips
Cup
Rise
Neck
Thigh
Shoulders
Sleeve
Device Size
apparelStyleList of possible values. e.g. Ladies, Men, Youth, etc.64 STRING FACETUnisex
Youth
Girls
Boys
Womens
WomensTall
Mens
MensTall
labelSizeList of possible values. The apparel items tagged size. e.g. XS, S, M, XL, etc.4 STRING FACETOSFA (One Size Fits All)
4XS (4 Extra Small)
3XS (3 Extra Small)
2XS (2 Extra Small)
XS (Extra Small)
S
M
L
XL (Extra Large)
2XL (2 Extra Large)
3XL (3 Extra Large)
4XL (4 Extra Large)
5XL (5 Extra Large)
CUSTOM

ErrorMessage Object

FieldDescriptionData TypeRequired?
codeThe numerical value of the codeNUMBERYES
descriptionResponse for any error requiring notification to requestor256 STRINGYES

Standardized Codes: The range of 100-199 has been reserved for standardized error codes. The number 999 has been reserved for an error codes that is a "General Error - Contact System Service Provider"

CodeDescription
100ID (customerID) not found
104This account is unauthorized to use this service. Please contact the service provider
105Authentication Credentials failed
110Authentication Credentials required
115wsVersion not found
120The following field(s) are required [Comma Delimited field names]
125Not Supported: [details]
130Product Id not found
135Product color not found
140Part Id not found
145Part color not found
150Part size not found
999General Error – Contact the System Service Provider

Code Samples

To be published under separate specification: " "

DATA MINING / ABUSE GUIDELINE

The use of services detailed within this specification are to be conducted within the current guidelines of the "Interface Data Use Guidelines Standards"

Validation of Services

Before you publish your endpoint, please ensure that it adheres to the promostandards.org spec by using the web service validation tool.

https://services.promostandards.org/webserviceValidator/home (opens in a new tab)

Select the service, version, method and input your endpoint. If the endpoint is correct you should receive a message of:

"The XML response is valid."

Diagrams