Skip to main content
Knowledge Base content is available to TradeCentric customers. To access all articles and videos, log in using single sign-on from Portal.

Purchase Order: Standard cXML payload

  • Updated

The OrderRequest payload sends a PO request to your eCommerce platform. 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 eCommerce platform must accept our standard cXML format. As a best practice, your platform should also return a success or error response. This article describes the standard cXML request and response formats.

Jump to:

Request payload (from TradeCentric)
Response payload (to TradeCentric)

 

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 from 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 from your eCommerce platform

    • 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 from 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

    Values: 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 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 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 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 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 (UNSPSC)

 

Response payload (to TradeCentric)

Once your eCommerce platform 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
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 eCommerce platform 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"

Was this article helpful?
0 out of 0 found this helpful
Return to top
© 2026 TradeCentric. All rights reserved.
Confidential and proprietary. For use by TradeCentric and organizations under NDA only. Not for public distribution.