Colorado Timberline APIA Practical Guide to Successful Integration

Order Protocol

Submit Method

The Request

Case Sensitive

All XML in these documents are case-sensative

Scalar Order Fields

OrderID

The order id from your system
AffiliateID

Your CT assigned AffiliateID
ShipToName

Full name of individual order is shipping to
ShipToContact

A name for an individual to contact regarding the order
AddressLine1

Primary address info
AddressLine2

Secondary address info (apartment number for example)
AddressLine3

Tertiary address info (seldom used)
City

Ship to city
Country

Ship to country
State

Ship to state
Province

Ship to province
Zip

Ship to zip code
Email

Ship to contact email address
Phone

Ship to contact phone number
SpecialInstructions

Instructions for our CSR staff
SpecialInstructions1

Instructions for our CSR staff
RequestedDeliveryDate

ignored field
ShipMethod

One of our supported shipping methods

Aggregate Order Components

You can think of aggregate fields as composed objects in an Object Oriented model. This in fact is how things are handled by the OPM in the CT reference client library.

The aggregate components are

  • Billing Information (PackingListInformaion in the XML payloads)
  • Order Items (Merchanide nodes in the XML payloads); Orders may have 1 or more Order Items

Billing Information

Order Items

Scalar Fields
Part Number
A part number; (see CT Inventory Paradigm for details on part number specification)
Printmode
Decoration Process to be used; (see Printmodes for details)
Aggregate Fields
Image
Image nodes have 2 components, one for a URL, the other for the location to apply the image at said url

Example Order Submission Payload

<Order OrderID="xxxx" AffiliateID="xxxxxx">
    <ShipToName>Bob Sanders</ShipToName>           
    <ShipToContact>Bob Sanders</ShipToContact>
    <AddressLine1>21 N. Long St.</AddressLine1>        
    <AddressLine2>Unit A</AddressLine2>
    <AddressLine3></AddressLine3>
    <City>Barrington Hills</City>                        
    <Country>US</Country>                  
    <State>Il</State>      
    <Province></Province>  
    <Zip>60010</Zip>
    <Email>madman@gmail.com</Email>
    <Phone>7086639935</Phone>
    <SpecialInstructions></SpecialInstructions>
    <SpecialInstructions2></SpecialInstructions2>
    <RequestedDeliveryDate></RequestedDeliveryDate>  
    <ShipMethod>UPSGROUND</ShipMethod>
    <PackingListInformation>
        <Logo URL="http://mydomain.com/images/graphic_tee.png" ></Logo>
        <Message1>Thanks for your order!</Message1>    
        <Message2>Refer your friends for a discount!</Message2>  
        <Message3></Message3>  
        <OrderDate>01/22/2010</OrderDate>
        <SoldToName>Bob Sanders</SoldToName>           
        <SoldToAddressLine1>21 N. Long St.</SoldToAddressLine1>    
        <SoldToAddressLine2>Unit A</SoldToAddressLine2>
        <SoldToAddressLine3></SoldToAddressLine3>
        <SoldToCity>Barrington Hills</SoldToCity>                        
        <SoldToCountry>US</SoldToCountry>                  
        <SoldToState>Il</SoldToState>      
        <SoldToProvince></SoldToProvince > 
        <SoldToZip>60010</SoldToZip>
        </PackingListInformation>
    <Merchandise Quantity="1" ItemID="item_id_01">             
        <PartNumber>COT27M</PartNumber>
            <Printmode>dark</Printmode>
        <ImageSet>
            <Image URL="http://mydomain.com/images/graphic_tee2.png" ViewName='front'/>
        </ImageSet>
               <!-- Required, but unused -->
        <PackageListOverride>
            <ItemName></ItemName>
            <ItemDescription></ItemDescription>
        </PackageListOverride>
    </Merchandise>
    <Merchandise Quantity="1" ItemID="item_id_03">             
        <PartNumber>COT32M</PartNumber>
            <Printmode>light</Printmode>   
        <ImageSet>
            <Image URL="http://mydomain.com/images/graphic_tee4.png" ViewName='front'/>
            <Image URL="http://mydomain.com/images/graphic_tee5.png" ViewName='back'/>
        </ImageSet>
               <!-- Required, but unused -->
        <PackageListOverride>
            <ItemName></ItemName>
            <ItemDescription></ItemDescription>
        </PackageListOverride>
    </Merchandise>      
</Order>

The Response

<?xml version="1.0" encoding="utf-8"?>
<success>
  <message>Your order was successfully submitted.</message>
  <affiliate_id> xxxxxx </affiliate_id>
  <po> xxxxxx </po>
  <confirmation_number> xxxxxx </confirmation_number>
</success>

Potential Response Error Codes

The error responses are very simple and the 1.5 implementation is so specific that many of the errors should not trigger specific handlers in your system. That said, the list of errors you can expect from order submissions are

'AffiliateIdError', 'ZaahIdError', 'ShipToNameError', 'Address1Error',
'CityError', 'CountryError', 'ZipError', 'ShippingMethodError', 'QuantityError',
'ViewNameError', 'URLError', 'StateError', 'XMLError', 'ImageURLError', 'PrintmodeError',
'PartNumberError', 'DupOrderIDError', 'DatabaseError'

These woud arrive as nodes of their own, within the root OrderResponse node, such as

<AffiliateIdError>Unrecognized AffiliateId</AffiliateIdError>

Notes on error codes

The XMLAccepted node in the response is a misnomer (only indicates XML was valid for parsing). In order to determine if there was a failure, the CT reference client library does the following:

  • check for HTTP response codes between 399 – 600 exclusive
  • check for any nodes which have an ‘Error’ component in the node name. this is done via the following XPATH expression:
    //*[contains(name(),'Error')]

You can also look for the presence of an OrderAccepted node, which indicates the order was accepted for processing on our end.

Error Handling Summary

Pertaining to the v1.5 API, you should essentially adopt a boolean paradigm when processing CT order submission errors. The granular error codes currently provided are not worth taking specific action in your system other than indicating some error occurred. Better granular error types will appear in the 2.0 service.

Order Shipped Notification

The Request

CT will send an XML payload to a designated URL which you must provide for CT to activate via HTTP POST.

<OrderShipped>
  <UDF_ORDER_CONFIRMATION>77785733</UDF_ORDER_CONFIRMATION>
  <CustomerNo>xxxxxxx</CustomerNo>
  <CustomerPONo>xxxx</CustomerPONo>
  <PackageNo>0001</PackageNo>
  <TrackingID />
  <Weight>0.00</Weight>
  <FreightAmtAddedToInv>0.00</FreightAmtAddedToInv>
  <ShipDate>2010-04-01 00:00:00</ShipDate>
  <ShipVia>DHLSMARTMAIL</ShipVia>
</OrderShipped>

The Response

CT expects nothing more than an HTTP 200 status from the header of the response. If the response code is something else, CT assumes there was an error in the transmission and schedules the notification for retry. There is a finite number of retries, so eventually CT will stop sending retries in the event of repeated failures.