cXML Orders

OrderRequest

The cXML OrderRequest document is used for sending orders from eProcurement systems to eCommerce systems. The requests are sent from the eProcurement server to the eCommerce server over HTTP(S). Each cXML OrderRequest document consists of header information (OrderRequestHeader) and a series of items (ItemOut).

The cXML[@payloadID] should be stored in both the eProcurement and eCommerce systems so it can be referenced by change orders and cancelled orders.

OrderRequestHeader

The OrderRequestHeader element contains header-level information for the order.

The following attributes on the OrderRequestHeader element should be included/processed:

  • orderID - The buyer’s order number (PO number)

  • orderDate - The date and time the order request was created (ISO 8601 format)

  • type - set to new for new orders, update for change orders, and delete for cancelled orders

  • requestedDeliveryDate - The requested delivery date reflects the time when the buyer is willing to receive the goods.

  • orderVersion - Should be set to "1" for the initial order. Each change order should increment the version by 1.

Total / Shipping / Tax

The OrderRequestHeader/Total element should be included in all orders and contain the total of all line item totals (excluding shipping/tax). The OrderRequestHeader/Shipping element should be included if the order contains shipping charges. The OrderRequestHeader/Tax element should be included if tax applies to the order.

<OrderRequestHeader orderID="789065" orderDate="2018-09-04T13:54:58Z" type="new" orderType="regular">
  <Total>
    <Money currency="USD">1542.00</Money>
  </Total>
  <ShipTo></ShipTo>
  <BillTo></BillTo>
  <Shipping>
    <Money currency="USD">15.78</Money>
    <Description xml:lang="en">Freight</Description>
  </Shipping>
  <Tax>
    <Money currency="USD">5.12</Money>
    <Description xml:lang="en">CA Sales Tax (9%)</Description>
  </Tax>
</OrderRequestHeader>

ShipTo/BillTo Addresses

The OrderRequestHeader/ShipTo and OrderRequestHeader/BillTo elements contain the shipping and billing addresses, respectively.

The usage of certain fields in the Address element will vary between eProcurement systems. The table below is a recommended way to use the fields based on the cXML specification and the USPS Delivery Address Guidelines.

Field Description On Mailing Label

[@addressID]

An address ID that is unique to each address

No

Name

The buyer’s company name

No

PostalAddress[@name]

A description of the address

No

PostalAddress/DeliverTo[1]

The full name of the person

Yes

PostalAddress/DeliverTo[2]

Location name

Yes

PostalAddress/Street[1]

Street 1

Yes

PostalAddress/Street[2]

Street 2

Yes

PostalAddress/City

City/town

Yes

PostalAddress/State

State abbreviation

Yes

PostalAddress/PostalCode

Zip code with no dashes/spaces

Yes

PostalAddress/Country[@isoCountryCode]

2 letter ISO Country Code

Yes*

PostalAddress/Country

Country Name

No

Email

Email address

No

Phone/TelephoneNumber/CountryCode

Country calling code

No

Phone/TelephoneNumber/AreaOrCityCode

Area code

No

Phone/TelephoneNumber/Number

Phone number with no dashes

No

Payment/PCard

The payment method for orders can either be purchase order (PO) or credit card (PCard). If the order is a credit card order, it will contain an OrderRequestHeader/Payment/PCard element that contains the credit card number, expiration date, and cardholders name. If a billing address is needed to charge the credit card, the address from the OrderRequestHeader/BillTo element should be used.

  • number - The credit card number with no spaces/dashes

  • expiration - The full expiration date in YYYY-MM-DD format. Typically the day should be the last day of the month.

  • name - The cardholders full name

<Payment>
  <PCard number="378282246310005" expiration="2018-04-30" name="JANE DOE"/>
</Payment>
Card Security Codes (CVV/CVC)

The cXML Standard does not provide a way to pass CVV information in OrderRequest documents. Furthermore, PCI Compliance 3.2.2 does not allow CVV codes to be stored under any circumstance. If you require the CVV code to process PCard payment information the following solutions are recommended:

  • Work with your payment processor to remove the CVV requirement. Most payment processors are able to charge credit cards without the CVV code.

  • Use a gateway solution that receives the orders and tokenizes the credit card information prior to forwarding the order to the supplier.

ItemOut elements

Each OrderRequest/ItemOut element represents a single line item on the order.

XPath Description Required

[@quantity]

Item quantity

Yes

[@lineNumber]

Line number

Yes

[@requestedDeliveryDate]

Requested delivery date

No

ItemID/SupplierPartID

Supplier part number or SKU for the item. This should be a unique identifier for the product.

Yes

ItemID/SupplierPartAuxiliaryID

Internal supplier ID for cart item

No

ItemDetail/UnitPrice

Unit price of item

Yes

ItemDetail/Description

Description of the item

Yes

ItemDetail/UnitOfMeasure

Unit of Measure

Yes

ItemDetail/Classification

Commodity code or product classification

Sometimes

ItemDetail/ManufacturerName

Manufacturer

No

ItemDetail/ManufacturerPartID

Manufacturer Part Number

No

Example ItemOut

<ItemOut lineNumber="1" quantity="1">
  <ItemID>
    <SupplierPartID>300925</SupplierPartID>
    <SupplierPartAuxiliaryID>275451934678936</SupplierPartAuxiliaryID>
  </ItemID>
  <ItemDetail>
    <UnitPrice>
      <Money currency="USD">22.43</Money>
    </UnitPrice>
    <Description xml:lang="en">Swingline 747 Stapler</Description>
    <UnitOfMeasure>EA</UnitOfMeasure>
    <Classification domain="UNSPSC">44121615</Classification>
    <ManufacturerPartID>747</ManufacturerPartID>
    <ManufacturerName>Swingline</ManufacturerName>
  </ItemDetail>
</ItemOut>

Response

The response should be a cXML Response document sent as the response body for the HTTP request. A success response should be returned if the order is a valid cXML OrderRequest and has been accepted for review. A success response does not necessarily indicate that the order will be successfully processed and shipped. Issues may occur after the order is accepted such as an item no longer being in stock. These types of issues should be handled using cXML OrderConfirmationRequest documents or by communicating directly with the buyer via email/phone.

Example Successful Response

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="1543504397.8857756@example.com" timestamp="2018-11-29T15:13:17+00:00">
  <Response>
    <Status code="200" text="OK">Success</Status>
  </Response>
</cXML>

Error Responses

The following error responses are recommended:

Scenario Code Text Message

POST body is missing

400

Bad Request

No XML in POST body

Credentials are not valid

401

Unauthorized

Sender identity or shared secret is invalid

Credit card is required

402

Payment Required

PCard information must be included in the Payment element

XML cannot be parsed

406

Not Acceptable

POST XML is not valid: ADDITIONAL_INFO

Order cannot be changed/cancelled

417

Expectation Failed

Order xxx cannot be changed or cancelled

Change orders are not supported

450

Not Implemented

Change orders are not supported

Error in eCommerce application

500

Internal Server Error

An un-handled error occurred while processing this request

 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="1539635340.9061692@example.com" timestamp="2018-04-15T20:29:00+00:00">
  <Response>
    <Status code="401" text="Unauthorized">Message goes here</Status>
  </Response>
</cXML>

Considerations

Response Time

The response should be sent back as quickly as possible, typically in under 5 seconds. If time consuming processing needs to be done when receiving an order, the order should be added to a queue for processing at a later time and the response should be sent back immediately. In general, the following processes should occur after the Response has been returned: validating ship-to/bill-to addresses, processing credit card information, and checking item inventory statuses.

Duplicate Orders

If the supplier does not send a Response document within the time allotted by the eProcurement system, the eProcurement system may resend the original document. It is the supplier’s responsibility to detect duplicate orders (2 orders with the same orderID and type="new") and ignore the duplicate orders.

Comments / Attachments

Order comments can be included with the OrderRequestHeader/Comments element. There are multiple ways to include attachments in cXML orders. Using OrderRequestHeader/Comments/Attachment elements with publicly accessible URL’s is the recommended method of including attachments.

<OrderRequestHeader orderID="789065" orderDate="2018-09-04T13:54:58Z" type="new" orderType="regular">
  <Comments>
    These are my comments
    <Attachment>
      <URL>https://s3.amazonaws.com/equallevelcdn/images/misc/swingline-747-rio-red.jpg</URL>
    </Attachment>
  </Comments>
</OrderRequestHeader>

Change Orders

Orders are updated by sending an OrderRequest document with the OrderRequestHeader[@type] attribute set to "update". Each updated document contains the entire order and should replace the order. A 417 error response should be returned if the order cannot be changed because it has already been processed. A 450 error response should be returned if the supplier does not support change orders.

Cancelled Orders

Orders are cancelled by sending an OrderRequest document with the OrderRequestHeader[@type] attribute set to "delete". The document should include the following fields:

Field Description

OrderRequestHeader[@orderDate]

The order date from the original order

OrderRequestHeader[@orderID]

The order number from the original order

OrderRequestHeader[@orderVersion]

The order version from the original order

OrderRequestHeader[@type]

Set to "delete"

DocumentReference[@payloadID]

The cXML[@payloadID] from the original cXML OrderRequest

 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="1539635340.9061692@example.com" timestamp="2018-04-15T20:29:00+00:00">
  <Header>
    <!-- credentials go here -->
  </Header>
  <Request>
    <OrderRequest>
      <OrderRequestHeader orderDate="2018-04-12T10:15:00+00:00" orderID="5493215" type="delete" orderVersion="1">
      <DocumentReference payloadID="1539611310.8502192@example.com"/>
    </OrderRequest>
  </Request>
</cXML>

Test Files

The files below are based on real orders from the specified eProcurement systems.

Share