Purchase Order: Standard cXML payload – TradeCentric

The OrderRequest payload sends a purchase order (PO) request to your system, such as your eCommerce platform or ERP system. For standard integrations that receive cXML payloads, the TradeCentric platform transforms the buyer's PO into our standard cXML 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 system must accept our standard cXML format. As a best practice, your system should also return a success or error response. This article describes the standard cXML request and response formats.

Jump to:

Request payload (from TradeCentric)

Request element details

cXML root
Header
Request

Response payload (to TradeCentric)

Response element details

cXML root
Response

Request payload (from TradeCentric)

The code block below shows an example OrderRequest payload in our standard cXML format:

cXML

HTTP POST

OrderRequest

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="93369535150910.10.57.136" timestamp="2022-11-18T10:57:13-05:00" version="1.2.045">
  <Header>
    <From>
      <Credential domain="NetworkID">
        <Identity>TEST_CORP</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="NetworkID">
        <Identity>SUPPLIER_INC</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="NetworkID">
        <Identity>TEST_CORP</Identity>
        <SharedSecret>password</SharedSecret>
      </Credential>
      <UserAgent>Storefront Integration v1.0</UserAgent>
    </Sender>
  </Header>
  <Request deploymentMode="production">
    <OrderRequest>
      <OrderRequestHeader orderID="PO-123" orderDate="2022-11-18" type="new">
        <Total>
          <Money currency="USD">142.09</Money>
        </Total>
        <ShipTo>
          <Address addressID="TN.04" isoCountryCode="US">
            <Name xml:lang="en">Test Corp. - Nashville Branch</Name>
            <PostalAddress>
              <DeliverTo>Contact Name</DeliverTo>
              <Street>123 Test St.; Suite A</Street>
              <City>Nashville</City>
              <State>TN</State>
              <PostalCode>37011</PostalCode>
              <Country isoCountryCode="US">United States</Country>
            </PostalAddress>
            <Email>contact@buyer.com</Email>
            <Phone>
              <TelephoneNumber>
                <CountryCode isoCountryCode="" />
                <AreaOrCityCode />
                <Number>888-555-9876</Number>
              </TelephoneNumber>
            </Phone>
          </Address>
        </ShipTo>
        <BillTo>
          <Address addressID="TN.04" isoCountryCode="US">
            <Name xml:lang="en">Test Corp. - Nashville Branch</Name>
            <PostalAddress>
              <DeliverTo>Contact Name</DeliverTo>
              <Street>123 Test St.; Suite A</Street>
              <City>Nashville</City>
              <State>TN</State>
              <PostalCode>37011</PostalCode>
              <Country isoCountryCode="US">United States</Country>
            </PostalAddress>
            <Email>contact@buyer.com</Email>
            <Phone>
              <TelephoneNumber>
                <CountryCode isoCountryCode="" />
                <AreaOrCityCode />
                <Number>888-555-9876</Number>
              </TelephoneNumber>
            </Phone>
          </Address>
        </BillTo>
        <Shipping>
          <Money currency="USD">10.09</Money>
          <Description xml:lang="en">FedEx 2Day</Description>
        </Shipping>
        <Tax>
          <Money currency="USD">8.64</Money>
          <Description xml:lang="en">Sales tax - 7% Tennessee</Description>
        </Tax>
        <Contact role="buyer">
          <Name xml:lang="en">Contact Name</Name>
          <Email>contact@buyer.com</Email>
          <Phone>
            <TelephoneNumber>
              <CountryCode isoCountryCode="" />
              <AreaOrCityCode />
              <Number>888-555-1234</Number>
            </TelephoneNumber>
          </Phone>
        </Contact>
      </OrderRequestHeader>
      <ItemOut quantity="3" lineNumber="101" requestedDeliveryDate="2022-12-25">
        <ItemID>
          <SupplierPartID>45L017</SupplierPartID>
          <SupplierPartAuxiliaryID>CART12-ITEM123</SupplierPartAuxiliaryID>
        </ItemID>
        <ItemDetail>
          <UnitPrice>
            <Money currency="USD">41.15</Money>
          </UnitPrice>
          <Description xml:lang="en">Item Description from storefront if provided</Description>
          <UnitOfMeasure>EA</UnitOfMeasure>
          <Classification domain="UNSPSC" />
        </ItemDetail>
      </ItemOut>
    </OrderRequest>
  </Request>
</cXML>

Request element details

A standard OrderRequest cXML payload has a root element, a Header element, and a Request element. The subsections below explain each element and its fields.

cXML root

Applies identifying information to the entire payload

Example

<cXML payloadID="93369535150910.10.57.136" timestamp="2022-11-18T10:57:13-05:00" version="1.2.045">
  ...
</cXML>

Root field breakdown

payloadID

Payload identifier

Type: String

Provides the unique payload identifier that the buyer generated, which you'll need to include in the invoice request payload if you create an invoice for this PO

Example: payloadID="93369535150910.10.57.136"
timestamp

Payload timestamp

Format: ISO 8601

Provides the date and time when the payload was created

Example: timestamp="2022-11-18T10:57:13-05:00"
version

cXML version

Type: String

Specifies the cXML version used for the payload

Example: version="1.2.045"

Header

Identifies the organizations involved in the transaction

Example

<Header>
  <From>
    <Credential domain="NetworkID">
      <Identity>TEST_CORP</Identity>
    </Credential>
  </From>
  <To>
    <Credential domain="NetworkID">
      <Identity>SUPPLIER_INC</Identity>
    </Credential>
  </To>
  <Sender>
    <Credential domain="NetworkID">
      <Identity>TEST_CORP</Identity>
      <SharedSecret>password</SharedSecret>
    </Credential>
    <UserAgent>Storefront Integration v1.0</UserAgent>
  </Sender>
</Header>

Header field breakdown

From
Buyer credential

Identifies the buyer organization
- domain Identifier type
  
  Type: String
  
  Specifies the type of identifier provided in the credential
  
  Example: domain="NetworkID" = Network identifier value for the eProcurement system
- Identity Identifier
  
  Type: String
  
  Provides the identifier value for the credential
  
  Example: <Identity>TEST_CORP</Identity>
To
Supplier credential

Identifies your organization
- domain Identifier type
  
  Type: String
  
  Specifies the type of identifier provided in the credential
  
  Example: domain="NetworkID" = Network identifier value for your system
- Identity Identifier
  
  Type: String
  
  Provides the identifier value for the credential
  
  Example: <Identity>SUPPLIER_INC</Identity>
Sender
Sending system credential

Identifies the sending eProcurement system and provides its authentication information
- domain Identifier type
  
  Type: String
  
  Specifies the type of identifier provided in the credential
  
  Example: domain="NetworkID" = Network identifier value for the eProcurement system
- Identity Identifier
  
  Type: String
  
  Provides the identifier value for the credential
  
  Example: <Identity>TEST_CORP</Identity>
- SharedSecret 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: <SharedSecret>password</SharedSecret>
- UserAgent Additional system identifier
  
  Type: String
  
  Provides an informational identifier, such as a name, for the sending system
  
  Example: <UserAgent>Storefront Integration v1.0</UserAgent>

Request

Provides the PO details, which are described in the subsections below

PO identification

Provides identifying information about the PO

Example

<Request deploymentMode="production">
  <OrderRequest>
    <OrderRequestHeader orderID="PO-123" orderDate="2022-11-18" type="new">

Request identification field breakdown

deploymentMode

Deployment mode

Type: StringValues: test, production

Specifies whether the request is for test or production

Example: deploymentMode="production"
OrderRequestHeader
PO header

Provides identifying information about the PO
- orderID Buyer PO identifier
  
  Type: String
  
  Provides the PO identifier that the buyer generated, which you'll need to include in the invoice request payload if you create an invoice for this PO
  
  Example: orderID="PO-123"
- orderDate Date
  
  Format: YYYY-MM-DD
  
  Provides the PO date from the buyer, which is typically the creation date
  
  Example: orderDate="2022-11-18"
- 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: type="new"

Total values

Provides total values for the entire PO

Example

<Total>
  <Money currency="USD">142.09</Money>
</Total>
<Shipping>
  <Money currency="USD">10.09</Money>
  <Description xml:lang="en">FedEx 2Day</Description>
</Shipping>
<Tax>
  <Money currency="USD">8.64</Money>
  <Description xml:lang="en">Sales tax - 7% Tennessee</Description>
</Tax>

Total values field breakdown

Total
Total item value

Provides the total value of all items in the PO, excluding any shipping or tax values
- Money Total value
  
  Type: Number
  
  Provides the value
  
  Example: <Money currency="USD">142.09</Money>
  - currency Currency
    
    Format: ISO 4217
    
    Specifies the currency used for the value
    
    Example: currency="USD"
Shipping
Total shipping value

Provides the total shipping value that the buyer expects for the PO
- Money Shipping value
  
  Type: Number
  
  Provides the value
  
  Example: <Money currency="USD">10.09</Money>
  - currency Currency
    
    Format: ISO 4217
    
    Specifies the currency used for the value
    
    Example: currency="USD"
- Description Shipping description
  
  Type: String
  
  Provides a description for the value
  
  Example: <Description xml:lang="en">FedEx 2Day</Description>
  - xml:lang Language
    
    Format: IETF BCP 47
    
    Specifies the language used for the description
    
    Example: xml:lang="en"
Tax
Total tax value

Provides the total tax value that the buyer expects for the PO
- Money Tax value
  
  Type: Number
  
  Provides the value
  
  Example: <Money currency="USD">8.64</Money>
  - currency Currency
    
    Format: ISO 4217
    
    Specifies the currency used for the value
    
    Example: currency="USD"
- Description Tax description
  
  Type: String
  
  Provides a description for the value
  
  Example: <Description xml:lang="en">Sales tax - 7% Tennessee</Description>
  - xml:lang Language
    
    Format: IETF BCP 47
    
    Specifies the language used for the description
    
    Example: xml:lang="en"

Shipping and billing addresses

Provides shipping and billing addresses for the PO

Example

<ShipTo>
  <Address addressID="TN.04" isoCountryCode="US">
    <Name xml:lang="en">Test Corp. - Nashville Branch</Name>
    <PostalAddress>
      <DeliverTo>Contact Name</DeliverTo>
      <Street>123 Test St.; Suite A</Street>
      <City>Nashville</City>
      <State>TN</State>
      <PostalCode>37011</PostalCode>
      <Country isoCountryCode="US">United States</Country>
    </PostalAddress>
    <Email>contact@buyer.com</Email>
    <Phone>
      <TelephoneNumber>
        <CountryCode isoCountryCode="" />
        <AreaOrCityCode />
        <Number>888-555-9876</Number>
      </TelephoneNumber>
    </Phone>
  </Address>
</ShipTo>
<BillTo>
  <Address addressID="TN.04" isoCountryCode="US">
    <Name xml:lang="en">Test Corp. - Nashville Branch</Name>
    <PostalAddress>
      <DeliverTo>Contact Name</DeliverTo>
      <Street>123 Test St.; Suite A</Street>
      <City>Nashville</City>
      <State>TN</State>
      <PostalCode>37011</PostalCode>
      <Country isoCountryCode="US">United States</Country>
    </PostalAddress>
    <Email>contact@buyer.com</Email>
    <Phone>
      <TelephoneNumber>
        <CountryCode isoCountryCode="" />
        <AreaOrCityCode />
        <Number>888-555-9876</Number>
      </TelephoneNumber>
    </Phone>
  </Address>
</BillTo>

Shipping and billing field breakdown

Address
Address details

Groups the shipping details and billing details
- addressID 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: addressID="TN.04"
- isoCountryCode Country code
  
  Format: ISO 3166
  
  Specifies the country for the address
  
  Example: isoCountryCode="US"
- Name Address name
  
  Type: String
  
  Provides the address name
  
  Example: <Name xml:lang="en">Test Corp. - Nashville Branch</Name>
  - xml:lang Language
    
    Format: IETF BCP 47
    
    Specifies the language used for the name
    
    Example: xml:lang="en"
- PostalAddress Postal address
  
  Provides the full address
  - DeliverTo Delivery contact name
    
    Type: String
    
    Provides the name of the delivery contact
    
    Example: <DeliverTo>Contact Name</DeliverTo>
  - Street Street address
    
    Type: String
    
    Provides the street address
    
    Example: <Street>123 Test St.; Suite A</Street>
  - City City
    
    Type: String
    
    Provides the city
    
    Example: <City>Nashville</City>
  - State Region
    
    Type: String
    
    Provides the state, province, or region either as a two-character code or a full name
    
    Example: <State>TN</State>
  - PostalCode Postal code
    
    Type: String
    
    Provides the postal code
    
    Example: <PostalCode>37011</PostalCode>
  - Country Country
    
    Type: String
    
    Provides the full country name
    
    Example: <Country isoCountryCode="US">United States</Country>
    
    isoCountryCode Country code
    
    Format: ISO 3166
    
    Specifies the country code
    
    Example: isoCountryCode="US"
- Email Email address
  
  Type: String
  
  Provides the email address associated with the address
  
  Example: <Email>contact@buyer.com</Email>
- Phone Phone number
  
  Groups the phone number details
  - TelephoneNumber Telephone number
    
    Provides the phone number associated with the address
    
    CountryCode Country code
    
    Type: String
    
    Provides the country code
    
    Example: blank in this payload
    
    AreaOrCityCode Area or city code
    
    Type: String
    
    Provides the area or city code
    
    Example: blank in this payload
    
    Number Phone number
    
    Type: String
    
    Provides the phone number
    
    Example: <Number>888-555-9876</Number>

Buyer contact

Provides details about the buyer contact for the overall PO

Example

<Contact role="buyer">
  <Name xml:lang="en">Contact Name</Name>
  <Email>contact@buyer.com</Email>
  <Phone>
    <TelephoneNumber>
      <CountryCode isoCountryCode="" />
      <AreaOrCityCode />
      <Number>888-555-1234</Number>
    </TelephoneNumber>
  </Phone>
</Contact>

Contact field breakdown

role

Contact role

Type: String

Specifies the type of contact provided

Example: role="buyer"
Name
Contact name

Type: String

Provides the contact's name

Example: <Name xml:lang="en">Contact Name</Name>
- xml:lang Language
  
  Format: IETF BCP 47
  
  Specifies the language used for the name
  
  Example: xml:lang="en"
Email

Contact email address

Type: String

Provides the contact's email address

Example: <Email>contact@buyer.com</Email>
Phone
Contact phone number

Groups the contact's phone number details
- TelephoneNumber Telephone number
  
  Provides the phone number values
  - CountryCode Country code
    
    Type: String
    
    Provides the country code for the phone number
    
    Example: blank in this payload
  - AreaOrCityCode Area or city code
    
    Type: String
    
    Provides the area or city code for the phone number
    
    Example: blank in this payload
  - Number Phone number
    
    Type: String
    
    Provides the phone number
    
    Example: <Number>888-555-1234</Number>

Items

Provides details about each of the line items in the PO

Note: We'll repeat the ItemOut element for each line item. 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

<ItemOut quantity="3" lineNumber="101" requestedDeliveryDate="2022-12-25">
  <ItemID>
    <SupplierPartID>45L017</SupplierPartID>
    <SupplierPartAuxiliaryID>CART12-ITEM123</SupplierPartAuxiliaryID>
  </ItemID>
  <ItemDetail>
    <UnitPrice>
      <Money currency="USD">41.15</Money>
    </UnitPrice>
    <Description xml:lang="en">Item Description from storefront if provided</Description>
    <UnitOfMeasure>EA</UnitOfMeasure>
    <Classification domain="UNSPSC" />
  </ItemDetail>
</ItemOut>

Items field breakdown

quantity

Quantity

RequiredType: Number

Provides the ordered item quantity

Example: quantity="3"
lineNumber

Line number

RequiredType: Number

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: lineNumber="101"
requestedDeliveryDate

Requested delivery date

Typically not requiredFormat: YYYY-MM-DD

Provides the delivery date that the buyer expects to receive the item by

Example: requestedDeliveryDate="2022-12-25"
ItemID
Item identifiers

Required

Groups the supplier item identifiers
- SupplierPartID Supplier part identifier
  
  Type: String
  
  Provides the item identifier, such as a part number or Stock Keeping Unit (SKU)
  
  Example: <SupplierPartID>45L017</SupplierPartID>
- SupplierPartAuxiliaryID Supplier auxiliary identifier
  
  Required for PO conversionType: String
  
  Provides a unique, additional item identifier, such as to indicate a specific color or packaging option
  
  Example: <SupplierPartAuxiliaryID>CART12-ITEM123</SupplierPartAuxiliaryID>
  
  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.
ItemDetail
Item details

Groups additional information about the item
- UnitPrice Unit price
  
  Typically not required but included
  
  Provides the price of one unit of the item after applying any discounts or special pricing
  - Money Unit price
    
    Type: Number
    
    Provides the value
    
    Example: <Money currency="USD">41.15</Money>
    
    currency Currency
    
    Format: ISO 4217
    
    Specifies the currency used for the value
    
    Example: currency="USD"
- Description Product description
  
  Typically requiredType: String
  
  Provides the item description
  
  Example: <Description xml:lang="en">Item Description from storefront if provided</Description>
  - xml:lang Language
    
    Format: IETF BCP 47
    
    Specifies the language used for the description
    
    Example: xml:lang="en"
- UnitOfMeasure Unit of measure
  
  Typically requiredType: String
  
  Provides the unit of measure for the item
  
  Example: <UnitOfMeasure>EA</UnitOfMeasure>
- Classification Product classification
  
  Provides the item classification code
  
  Example: <Classification domain="UNSPSC" />
  - domain Classification domain
    
    Type: String
    
    Specifies the type of classification code provided
    
    Example: domain="UNSPSC" = United Nations Standard Products and Services Code

Response payload (to TradeCentric)

Once your system processes the OrderRequest payload, it should return a cXML response payload. This payload should indicate whether you accepted the PO.

The code block below shows an example response in our standard cXML format:

cXML

HTTP response

PO response

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.0xx/cXML.dtd">
<cXML xml:lang="en-US" payloadID="93369535150910.10.57.136-response" timestamp="2022-11-18T10:57:14-05:00">
  <Response>
    <Status code="200" text="OK">Order accepted</Status>
  </Response>
</cXML>

Response element details

A standard cXML response has a root element and a Response element. The subsections below explain each element and its fields.

cXML root

Required Max use: 1

Applies identifying information to the entire response payload

Example

<cXML xml:lang="en-US" payloadID="93369535150910.10.57.136-response" timestamp="2022-11-18T10:57:14-05:00">
  ...
</cXML>

Root field breakdown

xml:lang

Language

RequiredFormat: IETF BCP 47

Specifies the language used for the response

Example: xml:lang="en-US"
payloadID

Payload identifier

RequiredType: String

Provides a unique identifier for the response

Example: payloadID="93369535150910.10.57.136-response"
timestamp

Response timestamp

RequiredFormat: ISO 8601

Provides the date and time when the response was created

Example: timestamp="2022-11-18T10:57:14-05:00"

Response

Required Max use: 1

Indicates that your system either accepted or rejected the PO

Example

<Response>
  <Status code="200" text="OK">Order accepted</Status>
</Response>

Response field breakdown

Status
Response status

Required

Specifies the success or error status and provides a message that can help TradeCentric's support team or your support team troubleshoot the request

Example: <Status code="200" text="OK">Order accepted</Status>, <Status code="400" text="Bad request">Order request is missing these fields: orderDate, ShipTo_City</Status>
- code Status code
  
  RequiredFormat: HTTP status code
  
  Provides the response status code
  
  Example: code="200" = success, code="400" = error
- text Status text
  
  RequiredType: String
  
  Provides a brief description of the status
  
  Example: text="OK", text="Bad request"

Request payload (from TradeCentric)

Request element details

cXML root

Payload identifier

Payload timestamp

cXML version

Header

Buyer credential

Supplier credential

Sending system credential

Request

PO identification

Deployment mode

PO header

Total values

Total item value

Total shipping value

Total tax value

Shipping and billing addresses

Address details

Buyer contact

Contact role

Contact name

Contact email address

Contact phone number

Items

Quantity

Line number

Requested delivery date

Item identifiers

Item details

Response payload (to TradeCentric)

Response element details

cXML root

Language

Payload identifier

Response timestamp

Response

Response status

Related articles