The purchase order (PO) request payload sends a PO request to your eCommerce platform. For standard integrations that receive JSON payloads, the TradeCentric platform transforms the buyer's PO into our standard JSON format. Then, our platform delivers the payload to your endpoint so that you can process the PO and create a sales order.
To receive POs as expected, your eCommerce platform must accept our standard JSON format. As a best practice, your platform should also return a success or error response. This article describes the standard JSON request and response formats.
Jump to:
Request payload (from TradeCentric)
The code block below shows an example PO request payload in our standard JSON format:
{
"mode": "production",
"shared_secret": "abracadabra",
"header": {
"from_domain": "NetworkID",
"from_identity": "TEST_CORP",
"to_domain": "NetworkID",
"to_identity": "SUPPLIER_INC",
"shared_secret": "password",
"po_payload_id": "93369535150910.10.57.136",
"po_order_id": "PO-123",
"po_order_date": "2022-11-18",
"po_order_type": "new",
"order_request_id": 12345678
},
"details": {
"total": 142.09,
"currency": "USD",
"shipping": 10.09,
"shipping_description": "FedEx 2Day",
"tax": 8.64,
"tax_description": "Sales tax - 7% Tennessee",
"ship_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"deliver_to": "Contact Name",
"streets": "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"
},
"bill_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"streets": "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"
},
"contact": {
"deliver_to": "Contact Name",
"email": "contact@buyer.com",
"phone": "888-555-1234"
}
},
"items": [
{
"line_number": "101",
"quantity": 3,
"supplier_id": "45L017",
"supplier_aux_id": "CART12-ITEM123",
"unitprice": 41.15,
"currency": "USD",
"description": "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant",
"uom": "EA",
"comments": "Please ship complete",
"session_key": "abcde12345fghij",
"cart_position": 0,
"extra_data": {
"requested_delivery_date": "2022-12-25"
}
}
]
}
Back to top
Request field details
A standard PO request JSON payload has a root object, a header object, a details object, and an items array. The subsections below explain each object and its fields.
JSON root
Applies identifying information to the entire payload
Example
{
"mode": "production",
"shared_secret": "abracadabra",
"header": {
...
},
"details": {
...
},
"items": [
...
]
}
Root request field breakdown
-
mode
Environment mode
Values: production, test
Specifies the buyer-provided mode value, which may or may not indicate whether the order should be regarded as a production order
Example: "production"
-
shared_secret
Your shared secret
Type: String
Provides your shared secret, which is the password that your organization and TradeCentric agreed to use for authentication
Example: "abracadabra"
-
header
PO header
Groups the PO identifiers, which are described in the Header section below
Example: "header": { ... }
-
details
PO totals and addresses
Groups the total values and address details, which are described in the Details section below
Example: "details": { ... }
-
items
PO line items
Groups the item details, which are described in the Items section below
Example: "items": [ ... ]
Provides identifying information about the PO
Example
"header": {
"from_domain": "NetworkID",
"from_identity": "TEST_CORP",
"to_domain": "NetworkID",
"to_identity": "SUPPLIER_INC",
"shared_secret": "password",
"po_payload_id": "93369535150910.10.57.136",
"po_order_id": "PO-123",
"po_order_date": "2022-11-18",
"po_order_type": "new",
"order_request_id": 12345678
}
Header field breakdown
-
from_domain
Buyer credential domain
Type: String
Provides the buyer credential domain from the original PO
Example: "NetworkID"
-
from_identity
Buyer identifier
Type: String
Provides the buyer identity value from the original PO
Example: "TEST_CORP"
-
to_domain
Supplier credential domain
Type: String
Provides your organization's credential domain from the original PO
Example: "NetworkID"
-
to_identity
Supplier identifier
Type: String
Provides your organization's identity value from the original PO
Example: "SUPPLIER_INC"
-
shared_secret
Buyer shared secret
Type: String
Provides the buyer's shared secret, which is the password that your organization and TradeCentric agreed to use to authenticate the buyer
Example: "password"
-
po_payload_id
Buyer payload identifier
Type: String
Provides the unique payload identifier that the buyer generated, which you'll need to include in the invoice payload if you create an invoice for this PO
Example: "93369535150910.10.57.136"
-
po_order_id
Buyer PO identifier
Type: String
Provides the PO identifier that the buyer generated, which you'll need to include in the invoice payload if you create an invoice for this PO
Example: "PO-123"
-
po_order_date
Date
Format: YYYY-MM-DD
Provides the PO date from the buyer, which is typically the creation date
Example: "2022-11-18"
-
po_order_type
Requested action
Type: String Values: new, update, delete
Specifies whether to create a new PO, or to edit or delete an existing one
Example: "new"
-
order_request_id
TradeCentric request identifier
Type: Number
Provides the unique payload identifier that our platform generated, which you'll need to include in any invoice, advanced shipment notice, or acknowledgement payloads for this PO
Example: 12345678
Details
Provides the PO details, which are described in the subsections below
Total values
Provides total values for the entire PO
Example
"details": {
"total": 142.09,
"currency": "USD",
"shipping": 10.09,
"shipping_description": "FedEx 2Day",
"tax": 8.64,
"tax_description": "Sales tax - 7% Tennessee"
...
}
Total values field breakdown
-
total
Total item value
Type: Number
Provides the total value of all items in the PO, excluding any shipping or tax values
Example: 142.09
-
currency
Currency
Format: ISO 4217
Specifies the currency for these values
Example: "USD"
-
shipping
Total estimated shipping value
Type: Number
Provides the total shipping value that the buyer expects for the PO
Example: 10.09
Note: This shipping value isn't considered the final amount that you're expected to charge. When you create the sales order for this PO, you should recalculate the shipping value.
-
shipping_description
Shipping description
Type: String
Provides a description for the shipping value
Example: "FedEx 2Day"
-
tax
Total expected tax value
Type: Number
Provides the total tax value that the buyer expects for the PO
Example: 8.64
Note: This tax value isn't considered the final amount that you're expected to charge. When you create the sales order for this PO, you should recalculate the tax value.
-
tax_description
Tax description
Type: String
Provides a description for the tax value
Example: "Sales tax - 7% Tennessee"
Shipping and billing addresses
Provides shipping and billing addresses for the PO
Example
"ship_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"deliver_to": "Contact Name",
"streets": "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"
},
"bill_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"streets": "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"
},
"contact": {
"deliver_to": "Contact Name",
"email": "contact@buyer.com",
"phone": "888-555-1234"
}
}
Shipping and billing field breakdown
-
ship_to and bill_to
Shipping and billing addresses
Group the shipping and billing information
address_id Identifier
Type: String
Provides the address identifier, which is the identifier from the buyer unless we've implemented a mapping to change the buyer's value to your preferred format
Example: "TN.04"
address_name Address name
Type: String
Provides the address name
Example: "Test Corp. - Nashville Branch"
deliver_to Delivery contact name
Type: 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.
streets Street address
Type: String
Provides the street address
Example: "123 Test St.; Suite A"
city City
Type: String
Provides the city
Example: "Nashville"
state Region
Type: String
Provides the state, province, or region either as a two-character code or a full name
Example: "TN"
postalcode Postal code
Type: String
Provides the postal code
Example: "37011"
country Country name
Type: String
Provides the full country name
Example: "United States"
country_code Country code
Format: ISO 3166
Provides the country code
Example: "US"
email Email address
Type: String
Provides the email address associated with the address
Example: "contact@buyer.com"
phone Phone number
Type: String
Provides the phone number associated with the address
Example: "888-555-9876"
-
contact
Buyer contact
Provides details about the buyer contact for the overall PO
deliver_to Contact name
Type: String
Provides the contact's name
Example: "Contact Name"
email Email address
Type: String
Provides the contact's email address
Example: "contact@buyer.com"
phone Phone number
Type: String
Provides the contact's phone number
Example: "888-555-1234"
Items
Provides details about each of the line items in the PO
Note: We'll repeat the object for each line item, using curly braces to group the item's fields. Some fields are specified as “Required” or “Typically required” to indicate the minimum requirements across most TradeCentric integrations. Your integration may have additional required fields depending on the needs of your organization and your buyer.
Example
"items": [
{
"line_number": "101",
"quantity": 3,
"supplier_id": "45L017",
"supplier_aux_id": "CART12-ITEM123",
"unitprice": 41.15,
"currency": "USD",
"description": "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant",
"uom": "EA",
"comments": "Please ship complete",
"session_key": "abcde12345fghij",
"cart_position": 0,
"extra_data": {
"requested_delivery_date": "2022-12-25"
}
}
]
Items field breakdown
-
line_number
Buyer line number
RequiredType: String
Provides the item line number from the buyer, which you'll need to include in any invoice, advanced shipment notice, or acknowledgement payloads for this PO
Example: "101"
-
quantity
Quantity
RequiredType: Number
Provides the ordered item quantity
Example: 3
-
supplier_id
Supplier item identifier
Type: String
Provides the item identifier, such as a part number or Stock Keeping Unit (SKU)
Example: "45L017"
-
supplier_aux_id
Cart line identifier
Required for PO conversionType: String
Provides a unique, additional item identifier, such as to indicate a specific color or packaging option
Example: "CART12-ITEM123"
Tip: You can use this identifier to associate the PO with the matching return cart and then to validate the PO using the cart. For example, you could reject POs that weren't created from their return carts within a specific timeframe, such as 60 days.
-
unitprice
Unit price
Typically not required but includedType: Number
Provides the price of one unit of the item after applying any discounts or special pricing
Example: 41.15
-
currency
Unit price currency
Format: ISO 4217
Specifies the currency for the unit price value
Example: "USD"
-
description
Description
Typically requiredType: String
Provides the item description
Example: "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant"
-
uom
Unit of measure
Typically requiredType: String
Provides the unit of measure for the item
Example: "EA"
-
comments
Buyer comment
Type: String
Provides the comment that the buyer added about the item
Example: "Please ship complete"
-
session_key
Punchout session identifier
Type: String
Provides the unique identifier for the punchout session associated with this item's return cart
Example: "abcde12345fghij"
-
cart_position
Cart position
Type: Number
Provides the zero-indexed position of the item in the original return cart
Example: 0 = the first position
-
extra_data
Additional item data
Groups any additional item attributes
requested_delivery_date Requested delivery date
Typically not requiredFormat: YYYY-MM-DD
Provides the delivery date that the buyer expects to receive the item by
Example: "2022-12-25"
Back to top
Response payload (to TradeCentric)
Once your eCommerce platform processes the PO request, it should return a JSON response body. This response should indicate whether you accepted the PO and created a sales order.
The code blocks below show example response payloads in our standard JSON format:
{
"error": "Order request is missing these fields: order_date, shipto_city"
}
Back to top
Response field details
The subsections below explain the fields of a success response and an error response.
Success response
Conditional Max use: 1
Provides your sales order identifier, confirming that your eCommerce platform created the order successfully
Example
{
"order_id": "987654"
}
Success response field breakdown
-
order_id
Sales order identifier
RequiredType: String
Provides your sales order identifier, such as an order number
Example: "987654"
Error response
Conditional Max use: 1
Provides an error message indicating that your eCommerce platform couldn't create the sales order
Example
{
"error": "Order request is missing these fields: order_date, shipto_city"
}
Error response field breakdown
-
error
Error message
RequiredType: String
Provides a message that can help our support team or your support team troubleshoot the request, such as:
HTTP 400: "Order request is missing these fields: order_date, shipto_city"
HTTP 401: "Authentication failed due to invalid credentials"
HTTP 504: "System didn't return a response before the timeout limit. Retry again later"
Back to top