The advanced shipment notice (ASN) payload sends an ASN request from your system, such as your eCommerce platform or ERP system, to the TradeCentric platform so that we can deliver the ASN to the buyer's eProcurement system. For standard integrations that send JSON payloads, we accept the ASN payload in our standard JSON format.
This article describes the standard JSON format to use for this payload.
Important: This ASN request payload is for ASNs 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 ASN request payload in our standard JSON format:
{
"apikey": "ABCD1234efgh5678.IJKL9012mnopq",
"params": {
"order_request_id": 12345678,
"shipnotice": {
"header": {
"ext_notice_id": "ASN-456",
"notice_date": "2022-11-18",
"po_payload_id": "93369535150910.10.57.136",
"po_order_id": "PO-123",
"po_order_date": "2022-11-01",
"shipment_date": "2022-11-18T08:30:00-05:00",
"delivery_date": "2022-11-22T15:30:00-05:00",
"shipment_type": "actual",
"requested_delivery_date": "2022-12-25",
"carrier_code": "UPSC",
"carrier_code_domain": "SCAC",
"carrier_name": "United Parcel Service Ground",
"shipment_identifier": "1Z56F78A0450293517",
"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": {
"custom_attribute": "sample_value"
}
},
"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",
"data": {
"custom_attribute": "sample_value"
}
},
"contact": {
"email": "contact@buyer.com",
"name": "Contact Name"
},
"data": {
"custom_attribute": "sample_value"
}
},
"items": [
{
"currency": "USD",
"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,
"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",
"total": 86.80,
"data": {
"custom_attribute": "sample_value"
}
}
],
"details": {
"total": 103.97,
"subtotal": 86.80,
"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 JSON ASN request payload has a root object and a params object, which contains a shipnotice 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 TradeCentric and your system, which you can use to authenticate the payload
Example: "ABCD1234efgh5678.IJKL9012mnopq"
-
params
ASN details
Required
Groups the ASN details, which are described in the Params section below
Example: "params": { ... }
Params
Provides the ASN details, which are described in the subsections below
PO reference
Required Max use: 1
Provides the PO that the ASN 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
ASN
Provides the ASN address, value, and item details, which are described in the subsections below
Optional Max use: 1
Provides identifying information for the ASN, and carrier and tracking information for the shipment
Note: With our standard integrations, we only support one shipping carrier and one shipment per ASN.
Example
"shipnotice": {
"header": {
"ext_notice_id": "ASN-456",
"notice_date": "2022-11-18",
"po_payload_id": "93369535150910.10.57.136",
"po_order_id": "PO-123",
"po_order_date": "2022-11-01",
"shipment_date": "2022-11-18T08:30:00-05:00",
"delivery_date": "2022-11-22T15:30:00-05:00",
"shipment_type": "actual",
"requested_delivery_date": "2022-12-25",
"carrier_code": "UPSC",
"carrier_code_domain": "SCAC",
"carrier_name": "United Parcel Service Ground",
"shipment_identifier": "1Z56F78A0450293517",
"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": {
"custom_attribute": "sample_value"
}
},
"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",
"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 ASN identifier
Required Type: String
Provides the ASN identifier that your organization generated
Example: "ASN-456"
-
notice_date
ASN date
Required Format: YYYY-MM-DD
Provides the ASN's issue date
Example: "2022-11-18"
-
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"
-
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_order_date
Buyer PO date
Required Format: YYYY-MM-DD
Provides the PO date from the PO request payload that we sent
Example: "2022-11-01"
-
shipment_date
Shipment date
Optional Format: ISO 8601
Provides the date or date and time when the shipment was sent
Example: "2022-11-18T08:30:00-05:00"
-
delivery_date
Delivery date
Optional Format: ISO 8601
Provides the date or date and time when the shipment is expected to arrive
Example: "2022-11-22T15:30:00-05:00"
-
shipment_type
Shipment type
Optional Values: actual, planned
Specifies whether the ASN is for an actual shipment or a planned one
Example: "actual"
-
requested_delivery_date
Requested delivery date
Optional Format: ISO 8601
Provides the delivery date or date and time that the buyer requested, if available
Example: "2022-12-25"
-
carrier_code
Carrier code
Optional Type: StringMax use: 1
Provides the code for the shipping carrier
Example: "UPSC" = United Parcel Service
-
carrier_code_domain
Carrier code type
Optional Type: StringMax use: 1
Specifies the type of carrier code provided
Example: "SCAC" = Standard Carrier Alpha Code
-
carrier_name
Carrier name
Optional Type: StringMax use: 1
Provides the name of the shipping carrier
Example: "United Parcel Service Ground"
-
shipment_identifier
Shipment identifier
Optional Type: String
Provides the tracking number that the shipping carrier assigned to the shipment
Example: "1Z56F78A0450293517"
-
ship_to and bill_to
Shipping and billing addresses
Optional
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.; Suite A"
city City
Required if address object is usedType: 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
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
OptionalType: Object
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
ASN contact
Optional
Provides details about the contact for the ASN
email Email address
Optional Type: String
Provides the contact's email address
Example: "contact@buyer.com"
name Contact name
Optional Type: String
Provides the contact's name
Example: "Contact Name"
-
data
Additional header data
OptionalType: Object
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
Optional Max use: Many
Provides details about each of the line items in the shipment
Note: Repeat the object for each line item, using curly braces to group the item's fields.
Example
"items": [
{
"currency": "USD",
"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,
"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",
"total": 86.80,
"data": {
"custom_attribute": "sample_value"
}
}
]
Items field breakdown
-
currency
Currency
Optional Format: ISO 4217
Specifies the currency for these values
Example: "USD"
-
line_number
Line number
Required Type: String
Provides the line number that your organization generated for the item
Example: "101"
-
quantity
Quantity
Required Type: Number
Provides the shipped 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
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
-
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"
-
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 item's discount value
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."
-
shipping
Item shipping value
Optional Type: Number
Provides the item's shipping value
Example: 0
-
shipping_title
Item shipping description
Optional Type: String
Provides a description or code to explain the item's shipping value
Example: "FedEx 2Day"
-
tax
Item tax value
Optional Type: Number
Provides the item's tax value
Example: 0
-
tax_rate
Item tax rate
Optional Type: Number
Provides the percentage rate of the item's tax value
Example: 0
-
tax_title
Item tax description
Optional Type: String
Provides a description or code to explain the item's tax value
Example: "No item-level tax"
-
total
Item total
Required Type: Number
Provides the total value for the line item after applying any discounts or tax and shipping values
Example: 86.80
-
data
Additional item data
OptionalType: Object
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
Optional Max use: 1
Provides total values for the ASN
Example
"details": {
"total": 103.97,
"subtotal": 86.80,
"currency": "USD",
"shipping": 10.09,
"shipping_title": "FedEx 2Day",
"tax": 8.64,
"tax_title": "Sales tax - 7% Tennessee"
}
Details field breakdown
-
total
ASN total
RequiredType: Number
Provides the total value after applying all discounts or tax and shipping values
Example: 103.97
-
subtotal
ASN subtotal
OptionalType: Number
Provides the total value of all line items before applying any discounts or tax and shipping values
Example: 86.80
-
currency
Value currency
RequiredFormat: ISO 4217
Specifies the currency for these values
Example: "USD"
-
shipping
Shipping value
OptionalType: Number
Provides the total shipping value
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
Example: 8.64
-
tax_title
Tax description
OptionalType: String
Provides a description of the tax value
Example: "Sales tax - 7% Tennessee"
Back to top
Response payload (from TradeCentric)
Once our platform receives the ASN request, we validate it and then return a JSON response body. This response indicates whether we created a final ASN 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 ASN identifier
Type: Number
Provides the unique ASN 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 ASN 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 invoice route.""No route reference was found.""json request is missing required data.""Order requested was invalid"
Back to top