Invoice 1.0.0


PromoStandards Logo

Invoice 1.0.0

Version: 1.0.0
Release Date: 2020-01-27

Document Change Log

VersionDateReason for ChangeAuthors
1.0.02020-01-27Version 1.0.0 ReleaseStephen Luisser - Essent Corporation Peter Tu - AnyPromo Paul Fleischman - PCNA


The following have contributed to the creation of this specification:


  • Stephen Luisser - Essent Corporation
  • Peter Tu - AnyPromo
  • Paul Fleischman - PCNA

Abstract and Recommended Audience

This document describes the technologies for the integration of suppliers and distributors in the Promotional Products Industry. It provides sample code for the interface and assumes the reader is fluent in web-based technologies.

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:


This function sends invoices based on the criteria provided in the queryType field.

Request: GetInvoiceRequest

FieldDescriptionData TypeRequired
wsVersionStandard Version of the Web Service (e.g., {1.0.0})64 STRINGTRUE
idcustomerId or other agreed upon Id64 STRINGTRUE
passwordPassword associated with customerId64 STRINGFALSE
queryTypeType of invoice query requestedEnumerated INTTRUE
referenceNumberPO number for queryType =1 or invoice number for queryType = 264 STRINGFALSE
requestedDateDate of the invoice for queryType = 3DATEFALSE
availableTimeStampBeginning date time since an invoice was made available in UTCDATETIMEFALSE

GetInvoiceRequest queryType

queryTypeShort NameDescription
1PO Number SearchSearch for invoices by purchase order number
2Invoice Number SearchSearch for invoice by invoice number
3Date SearchSearch for invoices with an invoice date specified by the requestedDate
4Available Date Time SearchSearch for invoices that were made available by a date time greater than the value specified by availableTimeStamp

Reply: GetInvoiceResponse

FieldDescriptionData TypeRequired
InvoiceArrayArray of invoice objectsARRAYFALSE
ServiceMessageArrayArray of ServiceMessage objectsOBJECTFALSE

Invoice Object

FieldDescriptionData TypeRequired
invoiceNumberThe invoice number64 STRINGTRUE
invoiceTypeThe type of invoice; values are enumerated: INVOICE, CREDIT MEMO64 STRINGTRUE
invoiceDateThe date the invoice was generatedDATETRUE
purchaseOrderNumberThe purchase order number64 STRINGFALSE
purchaseOrderVersionThe version of the purchase order number64 STRINGFALSE
BillToThe Bill To Address (AccountInfo Object)OBJECTFALSE
SoldToThe Sold To Address (AccountInfo Object)OBJECTFALSE
invoiceCommentsGeneral comments for the invoiceSTRINGFALSE
paymentTermsThe terms of the invoice64 STRINGFALSE
paymentDueDateThe Date the invoice must be paid in full without incurring late chargesDATETRUE
currencyThe currency of the invoice in ISO4217 formatSTRINGTRUE
fobIdThe fob point of the invoice64 STRINGFALSE
salesAmountThe amount of the sale in the specified currencyDOUBLETRUE
shippingAmountThe amount of the shipping charges in the specified currencyDOUBLETRUE
handlingAmountThe amount of the handling charges in the specified currencyDOUBLETRUE
taxAmountThe total amount of taxes in the currency specifiedDOUBLETRUE
invoiceAmountThe total amount of the invoice in the currency specified. Note: invoiceAmount = salesAmount + shippingAmount + handlingAmount + taxAmountDOUBLETRUE
advancePaymentAmountThe amount of any advanced payments in the currency specified. If the source system does not support including prepayments on an invoice this value should be set to zero.DOUBLETRUE
invoiceAmountDueThe total of the invoice amount due after applying any prepayments in the currency specified. Note: invoiceAmountDue = invoiceAmount - advancePaymentAmountDOUBLETRUE
invoiceDocumentUrlThe url to be able to download the physical invoice document.1024 STRINGFALSE
InvoiceLineItemsArrayAn array of invoice line item objectsOBJECT ARRAYTRUE
SalesOrderNumbersArrayAn array of sales order numbers included in the invoice64 STRING ARRAYFALSE
TaxArrayAn array of tax objects. The sum of the taxes within this array should equal the value in the taxAmount field.OBJECT ARRAYFALSE
invoicePaymentUrlThe url used to submit payment for the invoice1024 STRINGFALSE

InvoiceLineItem Object

FieldDescriptionData TypeRequired
invoiceLineItemNumberThe line item number of the line itemDOUBLEFALSE
productIdThe productId when the line item applies to a product64 STRINGFALSE
partIdThe partId when the line item applies to a product64 STRINGFALSE
chargeIdThe chargeId when the line item applies to a charge64 STRINGTRUE
purchaseOrderLineItemNumberThe line item number of the purchase order that the invoice references64 STRINGFALSE
orderedQuantityThe quantity ordered by the referenced purchase orderDOUBLEFALSE
invoiceQuantityThe quantity of the line item invoicedDOUBLETRUE
backOrderedQuantityThe quantity of the line item backorderedDOUBLEFALSE
quantityUOMThe unit of measure of the orderQuantity, invoicedQuantity, and 2 STRING (FACIT)TRUE
lineItemDescriptionA textual description of the line item1024 STRINGTRUE
unitPriceThe price of the unit in the currency of the purchase orderDOUBLETRUE
discountAmountAn amount of discount applied to the itemDOUBLEFALSE
extendedPriceThe extended price for the line item. Note: extendedPrice = (unitPrice * invoicedQuantity) - discountAmountDOUBLETRUE
distributorProductIdThe distributor’s productId for the item when the line item applies to a product64 STRINGFALSE
distributorPartIdThe distributor’s partId for the item when the line item applies to a product64 STRINGFALSE

AccountInfo Object

FieldDescriptionData TypeRequired
accountNameThe name of the account that will be invoiced for the purchase order. This also represents the companyName field from the PO.64 STRINGFALSE
accountNumberThe account number invoiced.64 STRINGFALSE
attentionToAttention To (first and last name of contact)64 STRINGFALSE
address1Address line 135 STRINGFALSE
address2Address line 235 STRINGFALSE
address3Address line 335 STRINGFALSE
cityThe city30 STRINGFALSE
regionThe 2 character US state abbreviation or 2-3 character non-US region.3 STRINGFALSE
postalCodeThe postal code10 STRINGFALSE
countryThe country in ISO 3166-2 format2 STRINGFALSE
emailThe email128 STRINGFALSE
phoneThe phone number32 STRINGFALSE

Tax Object

FieldDescriptionData TypeRequired
taxTypeThe type of tax the identifier applies to. Values are enumerated: “SALES”, “HST/GST”, “PST”, “VAT”.64 STRING (FACIT)TRUE
taxJurisdictionThe jurisdiction for the tax. For example, NJ, PA or Philadelphia City.64 STRINGTRUE
taxAmountThe amount of taxDOUBLETRUE

SalesOrderNumber Object

FieldDescriptionData TypeRequired
salesOrderNumberThe sales order associated with the invoice.64 STRINGTRUE


This function will send voided invoices based on the criteria provided in the queryType field.

Request: GetVoidedInvoiceRequest

FieldDescriptionData TypeRequired
wsVersionThe Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}64 STRINGTRUE
idThe customerId or any other agreed upon Id64 STRINGTRUE
passwordThe password associated with the customerId64 STRINGFALSE
queryTypeThe type of invoice query requestedEnumerated INTTRUE
referenceNumberThe purchase order number for queryType =1 or the invoice number for queryType = 264 STRINGFALSE
requestedDateThe date the invoice was voided for queryType = 3. This field does not include a time componentDATEFALSE
availableTimeStampBeginning date time since a voided invoice was made available in UTCDATETIMEFALSE

Reply: GetVoidedInvoiceResponse

FieldDescriptionData TypeRequired
VoidedInvoiceArrayAn array of voided invoice objectsARRAYFALSE
ServiceMessageArrayAn array of ServiceMessage objectsOBJECTFALSE

VoidedInvoice Object

FieldDescriptionData TypeRequired
invoiceNumberThe invoice number64 STRINGTRUE
voidDateThe date the invoice was voided. This field does not include a time component and it is up to the consuming party to determine if the data should be adjusted if the publishing party is on the other side of the international date line.DATETRUE

Appendix A: Service Messages

ServiceMessage Object

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

Standardized Codes

The range of 100-199 has been reserved for standardized error codes. The number 999 has been reserved for an error code that is a “General Error - Contact System Service Provider”.

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

Service Specific Codes

These error codes are only for this service.

901queryType not found
902queryType not supported
903No Invoices were found for the requested criteria


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


Before you publish your endpoint, please ensure that it adheres to the spec by using the web service validation tool located at: (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."


getInvoices Function

getVoidedInvoices Function