Product Data 2.0.0

PROMOTIONAL PRODUCTS DATA INTERFACE SPECIFICATION FOR WEB SERVICES

Product Data 2.0.0

PromoStandards Logo

DOCUMENT CHANGE LOG

VersionDateReason for ChangeAuthors
2.0.010/23/2019Initial ReleaseSee Contributors

CONTRIBUTORS

  • Paul Fleischman, Technical Lead, PCNA
  • Jon Norris, VP of Operations, Starline
  • Tim Dietrich, PromoStandards Consultant
  • Raj Mukherjee, Director of Integrations And ERP at Hit Promotional Products
  • Mike Olivieri, Manager of Integrations and Web Applications at BIC Graphic North America
  • Max Stepanskiy, Executive Director, Enterprise Architecture at Advertising Specialty Institute

Abstract and Recommended Audience

This document describes the technologies for integration of suppliers and distributors in the Promotional Products Industry. This document will discuss in detail the technology required in order to build the interface. Additionally, this document will provide sample code in order to use the interface.

This document will assume that the reader is fluent in web based technologies, and has knowledge of the language they plan to consume the web service in.

Background Information

All specifications will be built using the Simple Object Access Protocol (SOAP) over HTTPS as the foundation for the web services protocol stack in order to provide a standards based secure form of communication. More information on SOAP can be found at w3 (opens in a new tab)

PRODUCT DATA

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


getProduct()

This function provides the detailed 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 objects.ARRAYFALSE

REPLY: GetProductResponse

FieldDescriptionData TypeRequired?
ProductProduct InformationOBJECTFALSE
ServiceMessageArrayAn array of ServiceMessage objects.ARRAYFALSE

Product Object

FieldDescriptionData TypeRequired?
productIdThe associated product.64 STRINGTRUE
productNameThe Supplier name for the product256 STRINGTRUE
LocationDecorationArrayAn array of Location Decoration objectsOBJECT ARRAYTRUE
descriptionBasic product description or bulleted list of descriptions.2048 STRING ARRAYTRUE
priceExpiresDateThe date that the pricing in the ProductPriceGroupArray portion of the response expires.ISO 8601 DATEFALSE
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 data.NILLABLE BOOLEANTRUE
cautionCommentProduct cautionary comments1024 STRINGFALSE
isCloseoutIndicates if the product is a closeoutNILLABLE BOOLEANTRUE
lineNameLine Name / Division to which this product belongs64 STRINGFALSE
primaryImageURLThe URL of the product’s primary image. Any valid URL can be returned including prefixes like http and ftp.1024 STRINGFALSE
ProductPriceGroupArrayMarketing-oriented pricing information. Represented as an array of Product Price objects.OBJECT ARRAYFALSE
complianceInfoAvailableIndicates if there is information about this product via the Product Safety & Compliance service.NILLABLE BOOLEANFALSE
unspscCommodityCodeThe United Nations Standard Products and Services Code® (UNSPSC®) that best describes this product. Note that the enumerated values are the UNSPSC "Commodity" codes. For more information, refer to https://www.unspsc.org (opens in a new tab)INTFALSE
imprintSizeThe imprint Size256 STRINGFALSE
defaultSetUpChargeThe default setup charge for this product. Can be a textual description.1024 STRINGFALSE
defaultRunChargeThe default RUN charge for this product. Can be a textual description.1024 STRINGFALSE
FobPointArrayAn array of FOB points objectARRAYTRUE

LocationDecorationArray

An array of LocationDecoration objects that provide information about the decoration locations available for a product.

LocationDecoration Object

FieldDescriptionData TypeRequired?
locationNameThe name of the decoration location.255 STRINGTRUE
maxImprintColorsThe maximum number of imprint colors available, based on a decoration location and type.INTEGERFALSE
decorationNameThe name of the decoration method or type.64 STRINGTRUE
locationDecorationComboDefaultIndicates if this is the default location for the decoration.BOOLEANTRUE
priceIncludesIndicates if the price includes this decoration.BOOLEANTRUE

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

RelatedProduct Object

FieldDescriptionData TypeRequired?
relationTypeThe relationship type between two products.64 STRINGTRUE
productIdProduct Id associated with the related product.64 STRINGTRUE
partIdPart specific Id associated with the related product.64 STRINGFALSE

ProductPart

An array of ProductPart objects that provide detailed information about the specific parts of a product.

ProductPart Object

FieldDescriptionData TypeRequired?
partIdThe part Id64 STRINGTRUE
descriptionDescription or bulleted list of descriptions.2048 STRING (ARRAY)FALSE
countryOfOriginCountry of Origin in ISO 3166-1 Alpha 2 code format (Example: CA=Canada; US=United States)2 STRINGFALSE
ColorArrayInformation about the part colors. An array of Color objects.OBJECT ARRAYFALSE
primaryMaterialPrimary material of construction64 STRINGFALSE
SpecificationArraySpecifications OBJECTARRAYFALSE
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 Code1024 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
primaryColorThe "go to market" color. Represented as a Color Object.OBJECTFALSE

Color Object

FieldDescriptionData TypeRequired?
colorNameSupplier specific color name. Go to market color.64 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
standardColorNameThe standard color that best describes this color. Eventually may become an enumeration.64 STRINGFALSE

ApparelSize Object

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

Dimension Object

FieldDescriptionData TypeRequired?
dimensionUomThe dimensional unit of measure2 STRINGTRUE
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

ProductPackaging Object

An array of ProductPackaging objects that provide details about the packaging options available for a product, such as Gift Box, Cello Pack, Sleeve, etc.

ProductPackaging Object

FieldDescriptionData TypeRequired?
packageTypeThe specific type of product packaging, e.g., Box, Carton, etc.256 STRINGTRUE
descriptionDescription or details of the product packaging.2048 STRINGFALSE
quantityThe partId unit quantity included within this specific packaging option.DECIMALTRUE
dimensionUomThe unit of measure for the package dimensions.2 STRINGTRUE
depthThe depth/length of the package using the specified unit of measure.DECIMALFALSE
heightThe height of the package using the specified unit of measure.DECIMALFALSE
widthThe width of the package using the specified unit of measure.DECIMALFALSE

ShippingPackage Object

An array of ShippingPackage objects that provide details about the shipping packaging options available for a product, such as Carton, Box, Pallet, etc.

ShippingPackage Object

FieldDescriptionData TypeRequired?
packageTypeThe shipping package specific type for this shipping package e.g. Box, Carton, etc.256 STRINGTRUE
descriptionThe shipping package specific description.2048 STRINGFALSE
quantityThe partId unit quantity included within this specific shipping packaging option.DECIMALTRUE
dimensionUomThe weight unit of measure for the packageType.2 STRINGTRUE
depthThe depth/length of the shipping package in the dimensionUom unit of measure.DECIMALFALSE

Specification Object

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

getProductDateModified()

This function provides 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?
ProductDateModifiedArrayArray listing of all Product and Part specific Ids which have changed since the reference date requested (lastChangeDate). An array of ProductChange objects.OBJECT ARRAYTRUE
ServiceMessageArrayAn array of ServiceMessage objects.ARRAYFALSE

ProductDateModified Object

FieldDescriptionData TypeRequired?
productIdThe associated product64 STRINGTRUE
partIdThe associated part64 STRINGFALSE

getProductCloseOut()

This function provides 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 ARRAYFALSE
ServiceMessageArrayAn array of ServiceMessage objects.ARRAYFALSE

ProductCloseOut Object

FieldDescriptionData TypeRequired?
productIdThe associated product64 STRINGTRUE
partIdThe associated part64 STRINGFALSE

getProductSellable()

This function provides 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
localizationCountryISO 3166-1 Alpha 2 code for Country (Example: CA=Canada)2 STRINGTRUE

REPLY: GetProductSellableResponse

FieldDescriptionData TypeRequired?
ProductSellableArrayArray listing of all product and part specific Ids along with sellable status. An array of ProductSellable objects.OBJECT ARRAYTRUE
ServiceMessageArrayAn array of ServiceMessage objects.ARRAYFALSE

ProductSellable Object

FieldDescriptionData TypeRequired?
productIdThe associated product64 STRINGTRUE
partIdThe associated part64 STRINGFALSE
culturePointThe culture point64 STRINGFALSE

ServiceMessage Object

FieldDescriptionData TypeRequired?
codeThe numerical value of the codeINTEGERTRUE
descriptionResponse for any message requiring notification to requestor256 STRINGTRUE
severityThe severity of the message. Values are enumerated: {Error, Information, Warning}FACET 256 STRINGTRUE

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