The purchase order acknowledgment (POA) payload sends a POA request from your system, such as your eCommerce platform or ERP system, to the TradeCentric platform so that we can deliver the POA to the buyer's eProcurement system. For standard integrations that send JSON payloads, we accept the POA payload in our standard JSON format.
This article describes the standard JSON format to use for this payload.
Important: This payload is for POAs 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 POA request payload in our standard JSON format:
{
"apikey": "ABCD1234efgh5678.IJKL9012mnopq",
"params": {
"order_request_id": 12345678,
"confirmation": {
"header": {
"ext_notice_id": "POACK-789",
"notice_date": "2022-11-18",
"po_payload_id": "93369535150910.10.57.136",
"po_order_id": "PO-123",
"po_order_date": "2022-11-01",
"confirmation_status": "accept",
"ship_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"deliver_to": "Contact Name",
"street": "123 Test St.",
"city": "Nashville",
"state": "TN",
"postalcode": "37011",
"country": "United States",
"country_code": "US",
"email": "contact@buyer.com",
"phone": "888-555-9876",
"data": {
“custom_attribute": "sample_value”
}
},
"bill_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"street": "123 Test St.",
"city": "Nashville",
"state": "TN",
"postalcode": "37011",
"country": "United States",
"country_code": "US",
"email": "contact@buyer.com",
"phone": "888-555-9876",
"data": {
“custom_attribute": "sample_value”
}
},
"contact": {
"email": "contact@buyer.com",
"name": "Contact Name"
},
"data": {
“custom_attribute": "sample_value”
}
},
"items": [
{
"currency": "USD",
"_position": 1,
"line_number": "1",
"quantity": 2,
"part_id": "45L017",
"uom": "EA",
"po_line_number": "101",
"description": "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant",
"unitprice": 41.15,
"classification": "56101720",
"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.",
"shipping": 0,
"shipping_title": "FedEx 2Day",
"tax": 0,
"tax_rate": 0,
"tax_title": "No item-level tax",
"row_total": 86.80,
"confirmation_status": {
"quantity": 1,
"type": "accept",
"shipment_date": "2022-11-20",
"uom": "EA",
"comments": "Order accepted"
},
"data": {
“custom_attribute": "sample_value”
}
}
],
"details": {
"total": 103.97,
"subtotal": 85.33,
"currency": "USD",
"shipping": 10.09,
"shipping_title": "FedEx 2Day",
"tax": 8.64,
"tax_title": "Sales tax - 7% Tennessee"
}
}
}
}
Back to top
Request field details
A standard POA request JSON payload has a root object and a params object, which contains the POA data in a confirmation 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
RequiredType: String
Provides a secret value shared between TradeCentric and your system, which you can use to authenticate the payload
Example: "ABCD1234efgh5678.IJKL9012mnopq"
-
params
Payload details
Groups the POA details, which are described in the Params section below
Example: "params": { ... }
Params
Provides the POA details, which are described in the subsections below
PO reference
Required Max use: 1
Provides the PO that the POA is associated with
Example
"params": {
"order_request_id": 12345678,
...
}
PO reference field breakdown
-
order_request_id
PO request identifier
RequiredType: Number
Provides the unique PO request identifier from the PO request payload that we sent
Example: 12345678
Confirmation
Provides the POA status and PO details, which are described in the subsections below
Required Max use: 1
Provides identifying information about the POA
Example
"confirmation": {
"header": {
"ext_notice_id": "POACK-789",
"notice_date": "2022-11-18",
"po_payload_id": "93369535150910.10.57.136",
"po_order_id": "PO-123",
"po_order_date": "2022-11-01",
"confirmation_status": "accept",
"ship_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"deliver_to": "Contact Name",
"street": "123 Test St.",
"city": "Nashville",
"state": "TN",
"postalcode": "37011",
"country": "United States",
"country_code": "US",
"email": "contact@buyer.com",
"phone": "888-555-9876",
"data": {
“custom_attribute": "sample_value”
}
},
"bill_to": {
"address_id": "TN.04",
"address_name": "Test Corp. - Nashville Branch",
"street": "123 Test St.",
"city": "Nashville",
"state": "TN",
"postalcode": "37011",
"country": "United States",
"country_code": "US",
"email": "contact@buyer.com",
"phone": "888-555-9876",
"data": {
“custom_attribute": "sample_value”
}
},
"contact": {
"email": "contact@buyer.com",
"name": "Contact Name"
},
"data": {
“custom_attribute": "sample_value”
}
}
Header field breakdown
-
ext_notice_id
Supplier POA identifier
RequiredType: String
Provides the POA identifier that your organization generated
Example: "POACK-789"
-
notice_date
POA date
RequiredFormat: YYYY-MM-DD
Provides the POA's issue date
Example: "2022-11-18"
-
po_payload_id
Buyer payload identifier
RequiredType: String
Provides the buyer's payload identifier from the PO request payload that we sent
Example: "93369535150910.10.57.136"
-
po_order_id
Buyer PO number
RequiredType: String
Provides the buyer's PO identifier from the PO request payload that we sent
Example: "PO-123"
-
po_order_date
Buyer PO date
RequiredFormat: YYYY-MM-DD
Provides the PO date from the PO request payload that we sent
Example: "2022-11-01"
-
confirmation_status
POA status
RequiredType: StringValues: accept, reject, except, detail, backordered, requestToPay, replace
Specifies the POA status that your organization is communicating to the buyer
Example: "accept"
-
ship_to and bill_to
Shipping and billing addresses
Recommended
Group the buyer's shipping and billing information
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
Required if address object is usedType: String
Provides the street address
Example: "123 Test St."
city City
Required if address object is usedType: String
Provides the city
Example: "Nashville"
state Region
OptionalType: String
Provides the region
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
Required if address object is usedFormat: 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: {
“custom_attribute": "sample_value”
}
Note: We accept any structured JSON format, including key-value pairs, nested key-value pairs, and arrays.
-
contact
PO contact
Optional
Provides details about the contact for the POA
email Email address
OptionalType: String
Provides the contact's email address
Example: "contact@buyer.com"
name Contact name
OptionalType: String
Provides the contact's name
Example: "Contact Name"
-
data
Additional header data
OptionalMax use: Many
Groups any additional header attributes
Example: {
“custom_attribute": "sample_value”
}
Note: We accept any structured JSON format, including key-value pairs, nested key-value pairs, and arrays.
Items
Required Max use: Many
Provides details about each of the line items in the POA
Note: Repeat the object for each line item, using curly braces to group the item's fields.
Example
"items": [
{
"currency": "USD",
"_position": 1,
"line_number": "1",
"quantity": 2,
"part_id": "45L017",
"uom": "EA",
"po_line_number": "101",
"description": "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant",
"unitprice": 41.15,
"classification": "56101720",
"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.",
"shipping": 0,
"shipping_title": "FedEx 2Day",
"tax": 0,
"tax_rate": 0,
"tax_title": "No item-level tax",
"row_total": 86.80,
"confirmation_status": {
"quantity": 1,
"type": "accept",
"shipment_date": "2022-11-20",
"uom": "EA",
"comments": "Order accepted"
},
"data": {
“custom_attribute": "sample_value”
}
}
]
Items field breakdown
-
currency
Currency
OptionalFormat: ISO 4217
Specifies the currency for these values
Example: "USD"
-
_position
Array position
RequiredType: Number
Provides the one-indexed position of the item in the items array
Example: 1 = the first position
-
line_number
Line number
RequiredType: String
Provides the line number that your organization generated for the item
Example: "1"
-
quantity
Item quantity
RequiredType: Number
Provides the acknowledged item quantity
Example: 2
-
part_id
Supplier item identifier
RequiredType: String
Provides the item identifier, such as a part number or Stock Keeping Unit (SKU)
Example: "45L017"
-
uom
Unit of measure
RequiredType: String
Provides the item unit of measure
Example: "EA"
-
po_line_number
PO line number
RequiredType: String
Provides the line number from the PO request payload that we sent
Example: "101"
-
description
Item description
OptionalType: 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
RequiredType: Number
Provides the price of one unit of the item after applying any discounts or special pricing
Example: 41.15
-
classification
Classification code
OptionalType: String
Provides the item classification code, which we can map to the buyer's accepted format before sending the final payload
Example: "56101720"
-
comments
Item comments
OptionalType: 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
OptionalType: Non-negative number
Provides the value of the item's discount
Example: 0
-
discount_title
Item discount description
OptionalType: String
Provides a description or code to explain the item's discount value
Example: "Volume discount; 5% discount on quantities of ten or more"
-
shipping
Item shipping value
OptionalType: Number
Provides the item's shipping value
Example: 0
-
shipping_title
Item shipping description
OptionalType: String
Provides a description or code to explain the item's shipping value
Example: "FedEx 2Day"
-
tax
Item tax value
OptionalType: Number
Provides the item's tax value
Example: 0
-
tax_rate
Item tax rate
OptionalType: Number
Provides the percentage rate of the item's tax value
Example: 0
-
tax_title
Item tax description
OptionalType: String
Provides a description or code to explain the item's tax charge
Example: "No item-level tax"
-
row_total
Item row total
OptionalType: Number
Provides the total charge for the line item after applying any discounts or tax, shipping, and handling charges
Example: 86.80
-
confirmation_status
Item status details
Optional
Groups details about the status of the line item
quantity Quantity in status
OptionalType: Number
Provides the item quantity that the status applies to
Example: 1
type Item status
OptionalType: StringValues: accept, reject, except, detail, backordered, requestToPay, replace
Specifies the status that your organization is communicating for the quantity
Example: "accept"
shipment_date Shipping date
OptionalFormat: YYYY-MM-DD
Provides the shipping date for the quantity
Example: "2022-11-20"
uom Unit of measure
OptionalType: String
Provides the unit of measure for the quantity
Example: "EA"
comments Status comments
OptionalType: String
Provides any additional details about the status
Example: "Order accepted"
-
data
Additional item data
OptionalMax use: Many
Provides any additional item attributes
Example: {
“custom_attribute": "sample_value”
}
Note: We accept any structured JSON format, including key-value pairs, nested key-value pairs, and arrays.
Details
Required Max use: 1
Provides total values for the POA
Example
"details": {
"total": 103.97,
"subtotal": 85.33,
"currency": "USD",
"shipping": 10.09,
"shipping_title": "FedEx 2Day",
"tax": 8.64,
"tax_title": "Sales tax - 7% Tennessee"
}
Details field breakdown
-
total
POA total
RequiredType: Number
Provides the total value after applying all discounts or tax, shipping, and handling values
Example: 103.97
-
subtotal
Subtotal value
OptionalType: Number
Provides the total value of all line items before applying any discounts or tax, shipping, and handling values
Example: 85.33
-
currency
Currency
RequiredFormat: ISO 4217
Specifies the currency for these values
Example: "USD"
-
shipping
Shipping value
OptionalType: Number
Provides the total shipping value that your organization calculated
Example: 10.09
-
shipping_title
Shipping description
OptionalType: String
Provides a description or code to explain the shipping value
Example: "FedEx 2Day"
-
tax
Tax value
OptionalType: Number
Provides the total tax value that your organization calculated
Example: 8.64
-
tax_title
Tax description
OptionalType: String
Provides a description or code to explain the tax value
Example: "Sales tax - 7% Tennessee"
Back to top
Response payload (from TradeCentric)
Once our platform receives the POA request, we'll validate it and then return a JSON response body. This response will indicate whether we created a final POA 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": "Order requested was invalid"
}
}
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 POA identifier
Type: Number
Provides the unique POA identifier generated by our platform, indicating a success response
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 POA 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:
"Request body is not valid json""No parser class is defined for this route""No route reference was found""json request is missing required data""Order requested was invalid"
Back to top