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


The order id from your system

Your CT assigned AffiliateID

Full name of individual order is shipping to

A name for an individual to contact regarding the order

Primary address info

Secondary address info (apartment number for example)

Tertiary address info (seldom used)

Ship to city

Ship to country

Ship to state

Ship to province

Ship to zip code

Ship to contact email address

Ship to contact phone number

Instructions for our CSR staff

Instructions for our CSR staff

ignored field

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)
Decoration Process to be used; (see Printmodes for details)
Aggregate Fields
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>
    <City>Barrington Hills</City>                        
        <Logo URL="" ></Logo>
        <Message1>Thanks for your order!</Message1>    
        <Message2>Refer your friends for a discount!</Message2>  
        <SoldToName>Bob Sanders</SoldToName>           
        <SoldToAddressLine1>21 N. Long St.</SoldToAddressLine1>    
        <SoldToAddressLine2>Unit A</SoldToAddressLine2>
        <SoldToCity>Barrington Hills</SoldToCity>                        
        <SoldToProvince></SoldToProvince > 
    <Merchandise Quantity="1" ItemID="item_id_01">             
            <Image URL="" ViewName='front'/>
               <!-- Required, but unused -->
    <Merchandise Quantity="1" ItemID="item_id_03">             
            <Image URL="" ViewName='front'/>
            <Image URL="" ViewName='back'/>
               <!-- Required, but unused -->

The Response

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

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:

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.

  <TrackingID />
  <ShipDate>2010-04-01 00:00:00</ShipDate>

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.