The invoice request payload sends an invoice request from your system, such as your eCommerce platform or ERP system, to the TradeCentric platform so that we can deliver the invoice to the buyer's eProcurement system. For standard integrations that send JSON payloads, we accept the invoice request payload in our standard JSON format.
This article describes the standard JSON format to use for this payload.
Important: This invoice request payload is for invoices associated with purchase orders (POs) only. The payload must include the PO identifier from the PO request payload that we sent.
Jump to:
Request payload (to TradeCentric)
The code block below shows an example invoice request payload in our standard JSON format:
{
"apikey": "ABCD1234efgh5678.IJKL9012mnopq",
"params": {
"order_request_id": 12345678,
"invoice": {
"header": {
"purpose": "standard",
"ext_invoice_id": "INV-789",
"invoice_date": "2022-11-18",
"po_order_id": "PO-123",
"po_payload_id": "93369535150910.10.57.136",
"paymentTerms": [
{
"description": "NET30",
"due_date": "2023-02-23"
}
],
"ship_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"deliver_to": "Contact Name",
"street": "123 Test St.; Suite A",
"city": "Nashville",
"state": "TN",
"postalcode": "37011",
"country": "United States",
"country_code": "US",
"email": "contact@buyer.com",
"phone": "888-555-9876",
"data": {
"location_code": "TN.04"
}
},
"bill_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"street": "123 Test St.; Suite A",
"city": "Nashville",
"state": "TN",
"postalcode": "37011",
"country": "United States",
"country_code": "US",
"email": "contact@buyer.com",
"phone": "888-555-9876"
}
},
"details": {
"total": 103.97,
"currency": "USD",
"subtotal": 86.80,
"shipping": 10.09,
"shipping_title": "FedEx 2Day",
"tax": 8.64,
"tax_title": "Sales tax - 7% Tennessee",
"handling": 9.99,
"handling_title": "Per-pallet fee",
"discount": 11.55,
"discount_title": "B2B discount; 10% discount for Test Corp."
},
"items": [
{
"line_number": "101",
"quantity": 2,
"part_id": "45L017",
"uom": "EA",
"po_line_number": 1,
"description": "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant",
"unitprice": 41.15,
"currency": "USD",
"classification": "56101720",
"classdomain": "UNSPSC",
"manufacturer_id": "77-1206",
"comments": "This product is subject to a per-item packing fee for quantities less than 50.",
"discount": 0,
"discount_title": "Volume discount; 5% discount on quantities of ten or more.",
"handling": 2.25,
"handling_title": "Packing fee",
"shipping": 0,
"shipping_title": "FedEx 2Day",
"tax": 0,
"tax_rate": 0,
"tax_title": "Sales tax",
"subtotal": 82.30,
"row_total": 86.80
}
]
}
}
}
Back to top
Request field details
A standard JSON invoice request payload has a root object and a params object, which contains an invoice object. The subsections below explain each object and its fields.
JSON root
Required Max use: 1
Applies identifying information to the entire payload
Example
{
"apikey": "ABCD1234efgh5678.IJKL9012mnopq",
"params": {
...
}
}
Root request field breakdown
-
apikey
API key
Required Type: String
Provides a secret value shared between our platform and your system, which we can use to authenticate the payload
Example: "ABCD1234efgh5678.IJKL9012mnopq"
-
params
Invoice details
Required
Groups the invoice details, which are described in the Params section below
Example: "params": { ... }
Params
Provides the invoice details, which are described in the subsections below
PO reference
Required Max use: 1
Provides the PO that the invoice is associated with
Example
"params": {
"order_request_id": 12345678,
...
}
PO reference field breakdown
-
order_request_id
PO request identifier
Required Type: Number
Provides the unique PO request identifier from the PO request payload that we sent
Example: 12345678
Invoice
Provides the invoice address, value, and item details, which are described in the subsections below
Required Max use: 1
Provides identifying information about the invoice
Example
"invoice": {
"header": {
"purpose": "standard",
"ext_invoice_id": "INV-789",
"invoice_date": "2022-11-18",
"po_order_id": "PO-123",
"po_payload_id": "93369535150910.10.57.136",
"paymentTerms": [
{
"description": "NET30",
"due_date": "2023-02-23"
}
],
"ship_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"deliver_to": "Contact Name",
"street": "123 Test St.; Suite A",
"city": "Nashville",
"state": "TN",
"postalcode": "37011",
"country": "United States",
"country_code": "US",
"email": "contact@buyer.com",
"phone": "888-555-9876",
"data": {
"location_code": "TN.04"
}
},
"bill_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"street": "123 Test St.; Suite A",
"city": "Nashville",
"state": "TN",
"postalcode": "37011",
"country": "United States",
"country_code": "US",
"email": "contact@buyer.com",
"phone": "888-555-9876"
}
}
Header field breakdown
-
purpose
Invoice purpose
Optional Type: StringValues: standard, creditMemo
Specifies whether the document is a standard invoice or a credit memo
Example: "standard"
-
ext_invoice_id
Supplier invoice identifier
Required Type: String
Provides the invoice identifier that your organization generated
Example: "INV-789"
-
invoice_date
Invoice date
Required Format: YYYY-MM-DD
Provides the invoice's issue date
Example: "2022-11-18"
-
po_order_id
Buyer PO identifier
Required Type: String
Provides the buyer's PO identifier from the PO request payload that we sent
Example: "PO-123"
-
po_payload_id
PO payload identifier
Optional Type: String
Provides the buyer's payload identifier from the PO request payload that we sent
Example: "93369535150910.10.57.136"
-
paymentTerms
Payment terms
Optional
Provides the payment terms for the invoice
description Payment term code
Optional Type: String
Provides the expected payment timeframe using a term code or description
Example: "NET30" = due in 30 days, "EOM" = due at the end of the month
due_date Payment due date
Optional Format: YYYY-MM-DD
Specifies the payment due date
Example: "2023-02-23"
-
ship_to and bill_to
Shipping and billing addresses
Required
Group the buyer's shipping and billing information
Tip: To populate these fields, use the PO request payload that we sent.
address_id Identifier
OptionalType: String
Provides the address identifier
Example: "TN.04"
address_name Address name
OptionalType: String
Provides the address name
Example: "Test Corp. - Nashville Branch"
deliver_to Delivery contact name
OptionalType: String
Provides the name of the delivery contact
Example: "Contact Name"
Note: Typically, this field is only included in the ship_to field and not the bill_to field.
street Street address
RequiredType: String
Provides the street address
Example: "123 Test St.; Suite A"
city City
RequiredType: String
Provides the city
Example: "Nashville"
state Region
OptionalType: String
Provides the state, province, or region either as a two-character code or as a full name
Example: "TN"
postalcode Postal code
OptionalType: String
Provides the postal code
Example: "37011"
country Country name
OptionalType: String
Provides the full country name
Example: "United States"
country_code Country code
RequiredFormat: ISO 3166
Provides the country code
Example: "US"
email Email address
OptionalType: String
Provides the email address associated with the address
Example: "contact@buyer.com"
phone Phone number
OptionalType: String
Provides the phone number associated with the address
Example: "888-555-9876"
data Additional address data
OptionalMax use: Many
Groups any additional address attributes
Example: {
"location_code": "TN.04"
}
Note: We accept any structured JSON format, including key-value pairs, nested key-value pairs, and arrays.
Details
Required Max use: 1
Provides the total values of the entire invoice, including charges and discounts
Example
"details": {
"total": 103.97,
"currency": "USD",
"subtotal": 86.80,
"shipping": 10.09,
"shipping_title": "FedEx 2Day",
"tax": 8.64,
"tax_title": "Sales tax - 7% Tennessee",
"handling": 9.99,
"handling_title": "Per-pallet fee",
"discount": 11.55,
"discount_title": "B2B discount; 10% discount for Test Corp."
}
Details field breakdown
-
total
Invoice total
Required Type: Number
Provides the total charge of the invoice after applying all discounts or tax, shipping, and handling charges
Example: 103.97
-
currency
Document currency
Required Format: ISO 4217
Specifies the currency used for these charges
Example: "USD"
-
subtotal
Subtotal value
Optional Type: Number
Provides the total charge of all line items before applying any discounts or tax, shipping, and handling charges
Example: 86.80
-
shipping
Shipping charge
Optional Type: Number
Provides the total shipping charge
Example: 10.09
-
shipping_title
Shipping description
Optional Type: String
Provides a description or code to explain the shipping charge
Example: "FedEx 2Day"
-
tax
Tax charge
Optional Type: Number
Provides the total tax charge
Example: 8.64
-
tax_title
Tax description
Optional Type: String
Provides a description or code to explain the tax charge
Example: "Sales tax - 7% Tennessee"
-
handling
Handling charge
Optional Type: Number
Provides the total handling charge
Example: 9.99
-
handling_title
Handling description
Optional Type: String
Provides a description or code to explain the handling charge
Example: "Per-pallet fee"
-
discount
Discount value
Optional Type: Non-negative number
Provides the total discount value applied by your organization
Example: 11.55
-
discount_title
Discount description
Optional Type: String
Provides a description or code to explain the discount value
Example: "B2B discount; 10% discount for Test Corp."
Items
Required Max use: Many
Provides details about each of the line items in the invoice
Note: Repeat the object for each line item, using curly braces to group the item's fields.
Example
"items": [
{
"line_number": "101",
"quantity": 2,
"part_id": "45L017",
"uom": "EA",
"po_line_number": 1,
"description": "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant",
"unitprice": 41.15,
"currency": "USD",
"classification": "56101720",
"classdomain": "UNSPSC",
"manufacturer_id": "77-1206",
"comments": "This product is subject to a per-item packing fee for quantities less than 50.",
"discount": 0,
"discount_title": "Volume discount; 5% discount on quantities of ten or more.",
"handling": 2.25,
"handling_title": "Packing fee",
"shipping": 0,
"shipping_title": "FedEx 2Day",
"tax": 0,
"tax_rate": 0,
"tax_title": "Sales tax",
"subtotal": 82.30,
"row_total": 86.80
}
]
Items field breakdown
-
line_number
Line number
Required Type: String
Provides the line number that your organization generated for the item
Example: "101"
Note: For each group of line items, each line number must be unique.
-
quantity
Quantity
Required Type: Number
Provides the invoiced item quantity
Example: 2
-
part_id
Supplier item identifier
Required Type: String
Provides the item identifier, such as a part number or stock keeping unit (SKU)
Example: "45L017"
-
uom
Unit of measure
Required Type: String
Provides the item unit of measure, which we can map to the buyer's accepted format before sending the final payload
Example: "EA"
-
po_line_number
PO line number
Required Type: Number
Provides the line number from the PO request payload that we sent
Example: 1
-
description
Item description
Optional Type: String
Provides the item description
Example: "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant"
-
unitprice
Unit price
Required Type: Number
Provides the price of one unit of the item after applying any discounts or special pricing
Example: 41.15
-
currency
Unit price currency
Optional Format: ISO 4217
Specifies the currency used for the unit price value
Example: "USD"
-
classification
Classification code
Optional Type: String
Provides the item classification code, which we can map to the buyer's accepted format before sending the final payload
Example: "56101720"
-
classdomain
Classification type
Optional Type: String
Specifies the type of classification code provided
Example: "UNSPSC" = United Nations Standard Products and Services Code
-
manufacturer_id
Manufacturer part identifier
Optional Type: String
Provides the manufacturer's identifier for the item
Example: "77-1206"
-
comments
Item comments
Optional Type: String
Provides any additional details about the item
Example: "This product is subject to a per-item packing fee for quantities less than 50."
-
discount
Item discount
Optional Type: Non-negative number
Provides the value of the item's discount
Example: 0
-
discount_title
Item discount description
Optional Type: String
Provides a description or code to explain the item's discount value
Example: "Volume discount; 5% discount on quantities of ten or more."
-
handling
Item handling charge
Optional Type: Number
Provides the value of the item's handling charge
Example: 2.25
-
handling_title
Item handling description
Optional Type: String
Provides a description or code to explain the item's handling charge
Example: "Packing fee"
-
shipping
Item shipping charge
Optional Type: Number
Provides the value of the item's shipping charge
Example: 0
-
shipping_title
Item shipping description
Optional Type: String
Provides a description or code to explain the item's shipping charge
Example: "FedEx 2Day"
-
tax
Item tax charge
Optional Type: Number
Provides the value of the item's tax charge
Example: 0
-
tax_rate
Item tax rate
Optional Type: Number
Provides the percentage rate of the item's tax charge
Example: 0
-
tax_title
Item tax description
Optional Type: String
Provides a description or code to explain the item's tax charge
Example: "Sales tax"
-
subtotal
Item subtotal
Optional Type: Number
Provides the total charge for the line item before applying any discounts or tax, shipping, and handling charges
Example: 82.30
-
row_total
Item row total
Required Type: Number
Provides the total charge for the line item after applying any discounts or tax, shipping, and handling charges
Example: 86.80
Back to top
Response payload (from TradeCentric)
Once our platform receives the invoice request, we'll validate it and then return a JSON response body. This response will indicate whether we created a final invoice payload to transmit to the buyer.
The code blocks below show example response payloads in our standard JSON format:
{
"result": 12345678,
"errors": {}
}
{
"result": 0,
"errors": {
"code": "400",
"message": "json request is missing required data"
}
}
Back to top
Response field details
The success response and error response contain a result field and an errors object.
Response field breakdown
-
result
TradeCentric invoice identifier
Type: Number
Provides the unique invoice identifier generated by our platform, indicating a success response
Example: 12345678
Note: If the response is an error, this field's value will be 0.
-
errors
Error details
Type: Object
Explains why we couldn't create the final invoice payload, indicating an error response
Note: If the response is a success, this object will be blank.
code Error code
Type: String
Provides the error code
Example: "400"
message Error message
Type: String
Provides an error message that can help your support team or our support team troubleshoot the request, such as:
"json request is missing required data""Request body is not valid json""No parser class is defined for this invoice route""No route reference was found""Order requested was invalid"
Back to top