Purchase Order 1.0.0

PROMOTIONAL PRODUCTS DATA INTERFACE SPECIFICATION FOR WEB SERVICES

PromoStandards Logo

Purchase Order Service

Version: 1.0.0
Release Date: 2018-07-01

Document Change Log

VersionDateReason for ChangeAuthor
1.0.02018-07-01v1.0.0 publishSee contributors section

Contributors

The following have contributed to the creation of this specification:

  • Eric Shonebarger, CIO Hit Promotional Products, Inc
  • Jon Norris, VP of Operations Starline
  • Paul Fleischman, Technical Lead PCNA
  • Dustin Kessler, Enterprise Architect, Staples Promotional Products
  • Steve Luisser, VP of R&D, Essent

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)

Service Details:

Function: getSupportedOrderTypes()

This function returns the supported Order Types the vendor accepts.

Request: getSupportedOrderTypesRequest

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}STRINGVARCHAR(64)TRUE
idThe customerId or any other agreed upon Id.STRINGVARCHAR(64)TRUE
passwordThe password associated with the customerId.STRINGVARCHAR(64)FALSE

Response: getSupportedOrderTypesResponse

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
SupportedOrderTypes[]An array of supported order types for this supplier. Signifies which order types the supplier supports. Values are enumerated: “Blank”, “Sample”, “Simple” “Configured”ARRAYARRAYFALSE
ServiceMessageArrayAn array of ServiceMessage objects.OBJECTOBJECTFALSE

Function: sendPO()

This function will send a configured purchase order to a vendor. The purchase order is designed to work in conjunction with data from the Promostandards Product Pricing and Configuration web service. More information on Product Pricing and Configuration can be found at http://promostandards.org (opens in a new tab).

Absolutely! Here's the markdown documentation based on the provided details:

Request: sendPORequest

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}STRINGVARCHAR(64)TRUE
idThe customer Id or any other agreed upon Id.STRINGVARCHAR(64)TRUE
passwordThe password associated with the customer Id.STRINGVARCHAR(64)FALSE
POThe object containing the Purchase OrderOBJECTOBJECTTRUE

PO Object

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
orderTypeThe type of data transferred in the request with enumerated values: Blank, Sample, Simple, ConfiguredENUMERATED STRINGVARCHAR(64)TRUE
orderNumberPurchase order numberSTRINGVARCHAR(64)TRUE
orderDateThe date and time of the purchase orderDATEDATETRUE
lastModifiedThe date and time the purchase order was last modifiedDATEDATEFALSE
totalAmountThe total dollar amount of the purchase orderDOUBLEDECIMAL(12,4)TRUE
paymentTermsThe terms of the purchase order. i.e. NET15, NET30, etc.STRINGSTRINGFALSE
rushUsed to indicate a rush on the purchase orderBOOLEANBOOLEANTRUE
currencyThe currency the purchase order is transacted in ISO4217 formatSTRINGVARCHAR(3)TRUE
DigitalProofAn object containing preproduction digital proof informationOBJECTOBJECTFALSE
OrderContactArrayAn array of contact informationARRAYARRAYFALSE
ShipmentArrayAny array of purchase order shipmentsOBJECT ARRAYOBJECT ARRAYTRUE
LineItemArrayAn array of purchase order line itemsARRAYARRAYTRUE
termsAndConditionsThe terms and conditions for this purchase order. Information that is order specific or information dealing with the configuration or shipment of the order should not be entered here.STRINGVARCHAR(MAX)TRUE
salesChannelThe sales channelSTRINGVARCHAR(64)FALSE
promoCodeThe promotion codeSTRINGVARCHAR(64)FALSE
TaxInformationArrayAn array of TaxInformation objects related to calculating taxesARRAYARRAYFALSE

Object: DigitalProof

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
requiredA Boolean value set to TRUE indicates a proof is required for this purchase order; the value is FALSE otherwise.BOOLEANBOOLEANTRUE
DigitalProofAddressesArrayAn array containing DigitalProofAddress objects.ARRAYARRAYTRUE

Object: DigitalProofAddress

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
typeThe type of address of the digital proof. Values are enumerated: Email, WebserviceSTRINGVARCHAR(64)TRUE
emailThe address that the digital proof should be sent to prior to production.STRINGVARCHAR(128)TRUE
lineItemGroupingIdWhat line item group does this proof address link toINTINTTRUE

Object: TaxInformation

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
taxIdThe purchasers tax identifierSTRINGVARCHAR(64)TRUE
taxTypeThe type of tax the identifier applies to. Values are enumerated: “Hst-Gst”, “Pst”, “SalesTax”ENUMERATED STRINGVARCHAR(64)TRUE
taxExemptTax ExceptBOOLEANBOOLEANTRUE
taxJurisdictionTax JurisdictionsUNBOUNDED STRING ARRAYVARCHAR(64)TRUE
taxAmountThe amount of tax for this purchase orderDECIMALDECIMALFALSE

Object: LineItem

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
lineNumberThe line number of the line itemSTRINGVARCHAR(64)TRUE
descriptionThe description of the line item. For simple order type (not using a configuration), use this field to explain the details.STRINGVARCHAR(MAX)TRUE
lineTypeThe type of order; values are enumerated: “New” –A new purchase order with no prior order reference, “Repeat” —An exact repeat of a previous purchase order with the vendor, “Reference” –An order that has the same artwork as a previous order.ENUMERATED STRINGVARCHAR(64)TRUE
QuantityThe quantity object that contains the value and unit of measureOBJECTOBJECTFALSE
fobIdUsed to indicate the FOB point. Use fobId from the supplier’s Product Pricing and Configuration Service to populate this information.STRINGVARCHAR(64)FALSE
ToleranceDetailsThe object containing how tolerant this line is to overrun and underruns.OBJECTOBJECTTRUE
allowPartialShipmentsAllow partial shipments of this line itemBOOLEANBOOLEANTRUE
unitPriceThe unit price of the line itemDOUBLEDECIMAL(12,4)FALSE
lineItemTotalThe total for the line itemDOUBLEDECIMAL(12,4)TRUE
requestedShipDateThe date the line item is requested to ship from the FOB point.DATEDATEFALSE
requestedInHandsThe date the line item is requested to arrive at the shipping destinationDATEDATEFALSE
referenceSalesQuoteThe sales quote number associated with this purchase order line (if applicable).VARCHAR(64)VARCHAR(64)FALSE
ProgramProgram pricing information.OBJECTOBJECTFALSE
endCustomerSalesOrderThe distributor’s order number provided to the end customerVARCHAR(64)VARCHAR(64)FALSE
productIdThe manufacturer’s product id associated with the configuration data.STRINGVARCHAR(64)FALSE
customerProductIdThe distributor’s product idSTRINGVARCHAR(64)FALSE
lineItemGroupingIdAn identifier that allows configuration data to be spread out among multiple purchase order lines. Keep lineItemGroupingID unique when referencing the same product on the purchase order. Any change to the product, location, decoration, or artwork should produce a unique lineItemGroupingID to the purchase order.INTINTFALSE
PartArrayAn array of product part information. This array should be populated with information from the supplier’s PromoStandards Product Pricing and Configuration serviceARRAYARRAYFALSE
ConfigurationAn object containing line item configuration dataOBJECTOBJECTFALSE

Object: ToleranceDetails

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
toleranceAn enumerator specifying the quantity tolerance allowed: AllowOverRun, AllowUnderrun, AllowOverrunOrUnderrun, ExactOnly. Specifying AllowOverRun, AllowUnderrun or AllowOverrunOrUnderrun without a value and uom will result in the supplier’s discretion.ENUMERATED STRINGVARCHAR(64)TRUE
valueThe overrun/underrun permitted. This element is ignored if ExactOnly is specified for tolerance.DECIMALDECIMAL(12,4)FALSE
uomThe unit of measure for value element; enumerated values are: {Percent, Quantity}. This element is ignored if ExactOnly is specified for tolerance.ENUMERATED STRINGVARCHAR(10)FALSE

Object: Program

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
idThe program id associated with this purchase order line (if applicable).VARCHAR(64)VARCHAR(64)FALSE
nameThe program name associated with this purchase order line (if applicable).VARCHAR(64)VARCHAR(64)FALSE

Object: Quantity

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
valueThe quantity valueDECIMALDECIMAL(12,4)TRUE
uomThe unit of measure; values are enumerated. Values are: {BX, CA, DZ, EA, KT, PR, PK, RL, ST, SL, TH}. Enumerations: BX - Box, CA - Case, DZ - Dozen, EA - Each, KT - Kit, PR - Pair, PK - Package, RL - Roll, ST - Set, SL - Sleeve, TH - ThousandENUMERATED STRINGVARCHAR(2)TRUE

Object: Configuration

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
referenceNumberThe previous order number that this purchase order is referencingSTRINGVARCHAR(64)FALSE
referenceNumberTypeThe type of the prior order reference; values are enumerated: “PurchaseOrder”,”SalesOrder”, “JobOrWorkOrder”ENUMERATED STRINGVARCHAR(64)FALSE
preProductionProofIndicates that this line item is for a pre-production proofBOOLEANBOOLEANTRUE
ChargeArrayAn array of charge information. This array should be populated with information from the supplier’s PromoStandards Product Pricing and Configuration serviceARRAYARRAYFALSE
LocationArrayAn array of Decoration Location Information. This array should be populated with information from the supplier’s PromoStandards Product Pricing and Configuration serviceARRAYARRAYFALSE

Object: Part

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
partGroupAn identifier that links common line item parts togetherSTRINGVARCHAR(64)FALSE
partIdThe part Id from the supplier’s PromoStandards Product Pricing and Configuration serviceSTRINGVARCHAR(64)TRUE
customerPartIdHow the part is being represented to the distributor’s customerSTRINGVARCHAR(64)FALSE
customerSuppliedThe part will be supplied by the customer or another entity other than the supplierBOOLEANBOOLEANTRUE
descriptionThe description from the supplier’s PromoStandards Product Pricing and Configuration serviceSTRINGVARCHAR(MAX)FALSE
QuantityThe quantity object that contains the value and unit of measureOBJECTOBJECTTRUE
locationLinkIdAn array of location link Ids. This links the part to its configured locationsARRAY OF INTEGERSINT[]FALSE
unitPriceThe price of the part being referencedDECIMALDECIMAL(12,4)FALSE
extendedPriceThe unitPrice multiplied by the Quantity valueDECIMALDECIMAL(12,4)FALSE
ShipmentLinkArrayLink this part and a specified quantity to one or many shipmentsOBJECT ARRAYOBJECT ARRAYFALSE

Object: ShipmentLink

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
shipmentIdThe shipment IdINTINTTRUE
QuantityThe quantity object that contains the value and unit of measureOBJECTOBJECTTRUE

Object: Charge

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
chargeIdThe chargeId from the supplier’s PromoStandards Product Pricing and Configuration serviceSTRINGVARCHAR(64)TRUE
chargeNameThe chargeName from the supplier’s PromoStandards Product Pricing and Configuration serviceSTRINGVARCHAR(128)FALSE
descriptionThe charge description from the supplier’s PromoStandards Product Pricing and Configuration serviceSTRINGVARCHAR(MAX)FALSE
chargeTypeThe type of charge. Values are enumerated {Freight, Order, Run, Setup}ENUMERATED STRINGVARCHAR(64)TRUE
QuantityThe quantity object that contains the value and unit of measureOBJECTOBJECTTRUE
unitpriceThe price of the charge being referencedDECIMALDECIMAL(12,4)FALSE
extendedPriceThe unitPrice multiplied by the Quantity valueDECIMALDECIMAL(12,4)FALSE

Object: Location

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
locationLinkIdAn identifier to be used within the Part Array to link configured locations to a part. Due to different colors and sizes, identical locations may need to be decorated differentlyINTINTTRUE
locationIdThe locationId from the supplier’s PromoStandards Product Pricing and Configuration serviceINTINTTRUE
locationNameThe locationName from the supplier’s PromoStandards Product Pricing and Configuration serviceSTRINGVARCHAR(128)FALSE
DecorationArrayAn array of product decoration informationARRAYARRAYTRUE

Object: Decoration

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
decorationIdThe decorationId from the supplier’s PromoStandards Product Pricing and Configuration serviceINTINTTRUE
decorationNameThe decorationName from the supplier’s PromoStandards Product Pricing and Configuration serviceSTRINGVARCHAR(128)FALSE
ArtworkThe object containing the details of the artworkOBJECTOBJECTTRUE

Object: Artwork

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
refArtworkIdA pre-shared artwork Id that can be used by the supplier to find and reference the artworkSTRINGVARCHAR(64)FALSE
descriptionA textual description of the artwork being providedSTRINGVARCHAR(MAX)FALSE
DimensionsThe dimensions of the artworkOBJECTOBJECTFALSE
ArtworkFileArrayAn array of artwork file dataARRAYARRAYFALSE
instructionsAny instructions regarding the processing or modification of artwork. Adding instructions will cause delays in processingSTRINGVARCHAR(MAX)FALSE
LayersAn object that explains how the artwork layers or stops will be handledOBJECTOBJECTFALSE
TypesetArrayAn array of typeset dataARRAYARRAYFALSE
totalStitchCountThe total stitch count for the specified embroidery artINTINTFALSE

Object: ArtworkFile

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
fileNameThe file name and extension only of the artworkSTRINGVARCHAR(256)TRUE
fileLocationThe exact path/location to the artworkSTRINGVARCHAR(1024)TRUE
transportMechanismThe mechanism that will be used to transport the artwork; values are enumerated: “Email”, “Url”, “Ftp”, “ArtworkToFollow”ENUMERATED STRINGVARCHAR(64)TRUE
artworkTypeThe purpose of the artwork file; values are enumerated: “ProductionReady”, “VirtualProof”, “SupplierArtTemplate”, “NonProductionReady”ENUMERATED STRINGVARCHAR(64)TRUE

Object: Dimensions

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
geometryThe geometry of the decoration. Values are enumerated: {Circle, Rectangle, Other}ENUMERATED STRINGVARCHAR(64)TRUE
useMaxLocationDimensionsUse the maximum allowed imprint dimensions for this location. If this is set to true, all other dimension information is ignored except for geometryBOOLEANBOOLEANTRUE
heightThe height of the artwork; leave blank if the imprint is not rectangularDECIMALDECIMAL(12,4)FALSE
widthThe width of artwork; leave blank if the imprint is not rectangularDECIMALDECIMAL(12,4)FALSE
diameterThe diameter of the artwork; leave blank if the imprint is not circularDECIMALDECIMAL(12,4)FALSE
uomThe unit of measure for the decoration area in ISO 20022 ISO 20022 UOM (opens in a new tab)ENUMERATED STRINGVARCHAR(64)FALSE

Object: Layers

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
colorSystemThe color system to use: Cmyk, Other, Pms, Rgb, ThreadENUMERATED STRINGENUMERATED STRINGTRUE
LayerOrStopArrayAn array of layers for the artworkOBJECT ARRAYOBJECT ARRAYTRUE

Object: LayerOrStop

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
nameOrNumberThe name or number of the layer/stopSTRINGVARCHAR(64)TRUE
descriptionA human readable description of the layerSTRINGVARCHAR(MAX)TRUE
colorThe color value that corresponds to the colorSystem definedSTRINGVARCHAR(64)TRUE

Object: Typeset

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
sequenceNumberThe order of the typeset informationINTINTTRUE
valueThe typeset to be used on the orderSTRINGVARCHAR(1024)TRUE
fontThe font to use for the typesetSTRINGVARCHAR(64)FALSE
fontSizeThe font size to use for the typesetDECIMALDECIMALFALSE

Object: Shipment

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
customerPickupThe shipment will be a pickup and will not be shipped.BOOLEANBOOLEANTRUE
ShipToThe object containing the ship to informationOBJECTOBJECTTRUE
ThirdPartyAccountThe object containing the third party information for the shipping account to use and the business entity that is paying for the shipping. Known as ship using this account.OBJECTOBJECTFALSE
shipReferencesArray of two strings max of identifiers used as the reference fields used during the shipping process. A shipReference can be a PO number, customer number, company name, etc.STRING ARRAYVARCHAR(64)FALSE
packingListRequiredPacking list requiredBOOLEANBOOLEANTRUE
blindShipRequire blind shippingBOOLEANBOOLEANTRUE
allowConsolidationAllow consolidation of shipmentsBOOLEANBOOLEANTRUE
FreightDetailsThe details on the freight: carrier and serviceOBJECTOBJECTTRUE
commentsComments regarding the shipment for further clarification. Note: Use comments only when necessary, as it may cause delays in order processing.STRINGVARCHAR(MAX)FALSE

Object: FreightDetails

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
carrierThe carrier name of the shipping vendor being requested (e.g. “UPS”, “FEDEX”, etc.)STRINGVARCHAR(64)TRUE
serviceThe service code of the shipping vendor for the service being requested (e.g. GROUND, 2DAY, NEXTDAY, etc.)STRINGVARCHAR(64)TRUE

Object: ShipTo

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
shipmentIdThe shipment id that can be referenced in the ShipmentLink object.INTINTTRUE
ContactDetailsThe object containing the third party contact detailsOBJECTOBJECTTRUE

Object: ThirdPartyAccount

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
accountNameThe name of the account that will be used for shipping.STRINGVARCHAR(64)TRUE
accountNumberThe number of the account that will be used for shipping.STRINGVARCHAR(64)TRUE
ContactDetailsThe object containing the third party contact detailsOBJECTOBJECTTRUE

Object: Contact

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
contactTypeThe type of contact. Values are enumerated: {“Art”, “Bill”, “Expeditor”, “Order”, “Sales”, “Ship”, “Sold”}ENUMERATED STRINGVARCHAR(64)TRUE
ContactDetailsThe object that contains the details about the contact.OBJECTOBJECTTRUE
accountNameThe name of the account that will be invoiced for the purchase order. Should be populated when the contactType is Bill.STRINGVARCHAR(64)FALSE
accountNumberThe number of the account that will be invoiced for the purchase order. Should be populated when the contactType is Bill.STRINGVARCHAR(64)FALSE

Object: ContactDetails

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
attentionToAttention To (first and last name of contact)STRINGVARCHAR(35)FALSE
companyNameCompany NameSTRINGVARCHAR(35)FALSE
address1Address line 1STRINGVARCHAR(35)FALSE
address2Address line 2STRINGVARCHAR(35)FALSE
address3Address line 3STRINGVARCHAR(35)FALSE
cityThe citySTRINGVARCHAR(30)FALSE
regionThe 2 character US state abbreviation or 2-3 character non-US region.STRINGVARCHAR(3)FALSE
postalCodeThe postal codeSTRINGVARCHAR(10)FALSE
countryThe country in ISO 3166-2 formatSTRINGVARCHAR(2)FALSE
emailThe EmailSTRINGVARCHAR(128)FALSE
phoneThe phone numberSTRINGVARCHAR(32)FALSE
commentsComments regarding the contact for further clarification. Note: Use comments only when absolutely necessary, as it may cause delays in order processing.STRINGVARCHAR(MAX)FALSE

Object: SendPOResponse

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
transactionIdThe transaction identifier in response indicating a successful transfer of a schematically valid PO payload. Details provided regarding further order processing and potential errors.INTINTFALSE
ServiceMessageArrayAn array of ServiceMessage objects.OBJECTOBJECTFALSE

Appendix A: Service Messages

Object: ServiceMessage

FieldDescriptionWSDL Data TypeSQL Data TypeRequired?
codeThe numerical value of the codeINTINTTRUE
descriptionResponse for any message requiring notification to requestorSTRINGVARCHAR(256)TRUE
severityThe severity of the message. Values are enumerated: {Error, Information, Warning}ENUMERATED STRINGVARCHAR(64)TRUE

Standardized Codes

Note: 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]
999General Error – Contact the System Service Provider Details: [Details]

Service Specific Code

Note: These error codes are only for this service.

CodeDescription
200Duplicated transaction detected. PO was not submitted.
210Data violation: {0} (Occurs when a supplier does a pre-check on the data and finds that there is a mismatch of data and/or there are incorrect calculations)
220Field is not supported: {0}
230Field is partially supported: {0} (Use in situations where a supplier cannot accommodate different line level in-hands dates, fobs, etc. The responder will explain in the message what the course of action will be.)
240The following is not supported by the Simple order type: {0}
250The PO is received but there may be a delay in processing.

Diagrams

SendPO Function

Class Diagram for ServiceMessage and Additional Components