Field

Description

Data Type

Required

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}

64 STRING

TRUE

id

The customerId or any other agreed upon Id.

64 STRING

TRUE

password

The password associated with the customerId.

64 STRING

FALSE

queryType

The type of invoice query requested

Enumerated INT

TRUE

referenceNumber

The purchase order number for queryType =1 or the invoice number for queryType = 2.

64 STRING

FALSE

requestedDate

The date of the invoice for queryType = 3.  This field does not include a time component and it is up to the requesting party to determine if the date should be adjusted if the publishing party is on the other side of the international date line so that invoices are not missed.

DATE

FALSE

availableTimeStamp

Beginning date time since an invoice was made available in UTC.  This field must be included for queryType = 4.

DATETIME

FALSE

queryType

Short Name

Description

Best Practices

1

PO Number Search

Search for invoices by purchase order number

It is recommended to use the Order Status call to verify a PO has been closed before querying for its Invoice.

2

Invoice Number Search

Search for invoice by invoice number

3

Date Search

Search for invoices with an invoice date specified by the requestedDate

This is a search of the date of the Invoice.  Suppliers may limit the date range of this search due to data limitations.   It is recommended to contact the Supplier to verify what their date range limit may be.

It is recommended for Suppliers to use error code 125 for dates outside the cached invoice data with appropriate message. 

4

Available Date Time Search

Search for invoices that were made available by a date time greater than the value specified by availableTimeStamp

This is a search of data from the date the information was uploaded to PromoStandards.  Created date or upload date for a cached system.  Suppliers may limit the date range of this search due to data limitations. It is recommended to contact the Supplier to verify what their date range limit may be.

It is recommended for Suppliers to use error code 125 for dates outside the allowed date range. 

Field

Description

Data Type

Required

InvoiceArray

An array of invoice objects

ARRAY

FALSE

ServiceMessageArray

An array of ServiceMessage objects

OBJECT

FALSE

Field

Description

Data Type

Required

Best Practices

invoiceNumber

The invoice number

64 STRING

TRUE

invoiceType

The type of invoice; values are enumerated: “INVOICE”, “CREDIT MEMO”.  Currency amounts should be positive for type CREDIT MEMO.

64 STRING FACIT

TRUE

invoiceDate

The date the invoice was generated.  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.

OBJECT ARRAY

TRUE

It is possible to post or pre-date the invoice date. This is not necessarily the created date nor the upload date of the data.

purchaseOrderNumber

The purchase order number.  Consolidated Purchase Orders are not supported by this version.

64 STRING

FALSE

It is highly recommended to include the PO Number. Purchase Order numbers should match exactly as there is no wild card search available.

purchaseOrderVersion

The version of the purchase order number as submitted by the distributor.

64 STRING

FALSE

BillTo

The Bill To Address (AccountInfo Object)

OBJECT

FALSE

SoldTo

The Sold To Address (AccountInfo Object)

OBJECT

FALSE

invoiceComments

General comments for the invoice

STRING

FALSE

paymentTerms

The terms of the invoice

64 STRING

FALSE

paymentDueDate

The Date the invoice must be paid in full without incurring late charges.

DATE

TRUE

currency

The currency of the invoice in ISO4217 format

Enumerated STRING

TRUE

fobId

The fob point of the invoice

64 STRING

FALSE

salesAmount

The amount of the sale in the currency specified.

DOUBLE

TRUE

shippingAmount

The amount of the shipping charges in the currency specified.

DOUBLE

TRUE

handlingAmount

The amount of the handling charges in the currency specified.

DOUBLE

TRUE

taxAmount

The total amount of taxes in the currency specified.

DOUBLE

TRUE

invoiceAmount

The total amount of the invoice in the currency specified.

Note: invoiceAmount = salesAmount + shippingAmount + handlingAmount + taxAmount

DOUBLE

TRUE

advancePaymentAmount

The 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.

DOUBLE

TRUE

invoiceAmountDue

The total of the invoice amount due after applying any prepayments in the currency specified.

Note: invoiceAmountDue = invoiceAmount - advancePaymentAmount

DOUBLE

TRUE

This amount should be the balance due at the time of invoicing.

invoiceDocumentUrl

The url to be able to download the physical invoice document.

1024 STRING

FALSE

This is a recommended field.  This helps distributors reconcile the invoices.  If the Supplier is providing this URL, it should match the format of an invoice sent via email.  For security purposes, please make sure the URL is secure.

InvoiceLineItemsArray

An array of invoice line item objects

OBJECT ARRAY

TRUE

SalesOrderNumbersArray

An array of sales order numbers included in the invoice.

OBJECT ARRAY

FALSE

TaxArray

An array of tax objects.  The sum of the taxes within this array should equal the value in the taxAmount field.

OBJECT ARRAY

FALSE

invoicePaymentUrl

The url used to submit payment for the invoice

1024 STRING

FALSE

For security purposes, please make sure the URL is secure.

Field

Description

Data Type

Required

Best Practices

accountName

The name of the account that will be invoiced for the purchase order.  This also represents the companyName field from the PO.

64 STRING

FALSE

accountNumber

The account number invoiced.

64 STRING

FALSE

attentionTo

Attention To (first and last name of contact)

64 STRING

FALSE

address1

Address line 1

35 STRING

FALSE

If including a street address, it is recommended to include all fields needed for an address.

address2

Address line 2

35 STRING

FALSE

address3

Address line 3

35 STRING

FALSE

city

The city

30 STRING

FALSE

region

The 2 character US state abbreviation or 2-3 character non-US region.

3 STRING

FALSE

postalCode

The postal code

10 STRING

FALSE

country

The country in ISO 3166-2 format

2 STRING

FALSE

email

The email

128 STRING

FALSE

phone

The phone number

32 STRING

FALSE

Field

Description

Data Type

Required

Best Practices

invoiceLineItemNumber

The line item number of the line item

DOUBLE

FALSE

productId

The productId when the line item applies to a product.

64 STRING

FALSE

partId

The partId when the line item applies to a product.

64 STRING

FALSE

It is recommended to include either a partID or chargeID

chargeId

The chargeId when the line item applies to a charge.

64 STRING

FALSE

It is recommended to include either a partID or chargeID

purchaseOrderLineItemNumber

The line item number of the purchase order that the invoice references

64 STRING

FALSE

If the Supplier system is able to capture this, it is recommended to put this in.  It enables the distributor to do a 3-way match.

orderedQuantity

The quantity ordered by the referenced purchase order

DOUBLE

FALSE

invoiceQuantity

The quantity of the line item invoiced.

DOUBLE

TRUE

backOrderedQuantity

The quantity of the line item backordered. 

DOUBLE

FALSE

quantityUOM

The unit of measure of the orderQuantity, invoicedQuantity, and backOrderedQuantity

2 STRING FACIT

TRUE

Enumerated.  See Below

lineItemDescription

A textual description of the line item

1024 STRING

TRUE

unitPrice

The price of the unit in the currency of the purchase order

DOUBLE

TRUE

discountAmount

An amount of discount applied to the item.

DOUBLE

FALSE

This should be the discount price at the extended price (line item) level not the unit price level.

extendedPrice

The extended price for the line item

Note: extendedPrice = (unitPrice * invoicedQuantity) - discountAmount

DOUBLE

TRUE

distributorProductId

The distributor’s productId for the item when the line item applies to a product.

64 STRING

FALSE

distributorPartId

The distributor’s partId for the item when the line item applies to a product.

64 STRING

FALSE

Field

Description

Data Type

Required

Best Practices

salesOrderNumber

The sales order associated with the invoice.

64 STRING

TRUE

Field

Description

Data Type

Required

Best Practices

taxType

The type of tax the identifier applies to. Values are enumerated: “SALES”, “HST/GST”, “PST”, “VAT”.

64 STRING FACIT

TRUE

This is tax at the order level.

taxJurisdiction

The jurisdiction for the tax.  For example, NJ, PA or Philadelphia City.

64 STRING

TRUE

taxAmount

The amount of tax

DOUBLE

TRUE

Field

Description

Data Type

Required

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}

64 STRING

TRUE

id

The customerId or any other agreed upon Id.

64 STRING

TRUE

password

The password associated with the customerId.

64 STRING

FALSE

queryType

The type of invoice query requested

Enumerated INT

TRUE

referenceNumber

The purchase order number for queryType =1 or the invoice number for queryType = 2.

64 STRING

FALSE

requestedDate

The date the invoice was voided for queryType = 3.  This field does not include a time component and it is up to the requesting party to determine if the date should be adjusted if the publishing party is on the other side of the international date line so that invoices are not missed.

DATE

FALSE

availableTimeStamp

Beginning date time since a voided invoice was made available in UTC.  This field must be included for queryType = 4.

DATETIME

FALSE

queryType

Short Name

Description

Best Practices

1

PO Number Search

Search for voided invoices by purchase order number

2

Invoice Number Search

Search for voided invoice by invoice number

3

Date Search

Search for invoices with a voided date specified by the requestedDate

This is a search of the date of the Invoice.  Suppliers may limit the date range of this search due to data limitations.   It is recommended to contact the Supplier to verify what their date range limit may be.

It is recommended for Suppliers to use 125 for dates outside the cached invoice data with appropriate message.   

4

Available Date Time Search

Search for voided invoices that were made available by a date time greater than the value specified by availableTimeStamp

This is a search of data from the date the information was uploaded to PromoStandards.  Created date or upload date for a cached system.  Suppliers may limit the date range of this search due to data limitations. It is recommended to contact the Supplier to verify what their date range limit may be.

It is recommended for Suppliers to use 125 for dates outside the cached invoice data with appropriate message.

Field

Description

Data Type

Required

VoidedInvoiceArray

An array of voided invoice objects

ARRAY

FALSE

ServiceMessageArray

An array of ServiceMessage objects

OBJECT

FALSE

Field

Description

Data Type

Required

Best Practices

invoiceNumber

The invoice number

64 STRING

TRUE

voidDate

The 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.

DATE

TRUE

Field

Description

Data Type

Enumeration Values

Best Practices

wsVersion

The Standard Version of the Web Service being referenced

64 STRING FACIT

1.0.0

invoiceType

The type of invoice

64 STRING FACIT

INVOICE

CREDIT MEMO

quantityUOM

The unit of measure for quantity based field

2 STRING FACIT

BX (Box)

CA (Case)

DZ (Dozen)

EA (Each)

KT (Kit)

PR (Pair)

PK (Package)

RL (Roll)

ST (Set)

SL (Sleeve)

TH (Thousand)

taxType

The type of tax

64 STRING FACIT

SALES

HST/GST

PST

VAT

Field

Description

Data Type

Required

code

The numerical value of the code

INT

TRUE

description

Response for any message requiring notification to requestor

256 STRING

TRUE

severity

The severity of the message.  Values are enumerated: {Error, Information, Warning}

ENUMERATED 64 STRING

TRUE

Code

Description

100

ID (customerID) not found

104

This account is unauthorized to use this service.  Please contact the service provider

105

Authentication Credentials failed

110

Authentication Credentials required

115

wsVersion not found

120

The following field(s) are required [Comma Delimited field names]

125

Not Supported: [details]

999

General Error – Contact the System Service Provider

Code

Description

901

queryType not found

902

queryType not supported

903

No Invoices were found for the requested criteria