The Order Model (API Terminology Explained #14)

In my last blog post in the series “API Terminology Explained”, I told you about our shipping type model.
In this blog post, I will introduce the order model. Understanding the order model allows you to retrieve and create orders on the Spreadshirt platform using Spreadshirt API v1.

Understanding the Order Model

In our terminology, an order contains a set of abstract order items that link concrete order item elements. Right now, two concrete order item elements are supported: Spreadshirt product and article.
A typical order, e.g. an order with two products, is illustrated in the picture above. An order has right now the following characteristics:

  • Core Data: Each order has a shop assigned that represents the shop the products or articles are ordered for. It also has two attributes created and modified, that tell you when the order was created and when it was last modified.
  • Order Items: An order can have one or more order items. An order item represents an abstract item added to the order. Each order item has a description, a quantity, a price, a shop and a concrete order item element.
    The concrete order item element has a type attribute, which can right now be set to the supported types sprd:article or sprd:product, and a xlink:href attribute which links the actual product or article that is available via the API. Depending on the type, one can set type specific element properties. In case of Spreadshirt article and product, these properties are size and appearance.
    Please note that price and description are taken from the item linked by the order item element. Quantity is always a value greater equal 1.
    You can only add products or articles to an order, if they are available in the desired size and appearance (see product’s product type stock states). Some products do not allow to change the default color (freeColorSelection = false) and thus can not be added to the order in a different appearance than the configured one.
    An order item also has two attributes created and modified that tell you when the order item was created and when it was last modified.
    It can also have a baseOrderItem attribute that tell you which order item is the predecessor order item of the current one. This can happen for example if a customer sends an ordered item back to Spreadshirt and we ship it again to the customer.
  • Payment: The payment block allows to provide the necessary payment information for the order. Right now, we only support EXTERNAL_FULFILLMENT as payment type, which means that the partner orders products or articles for his customers on his account and has either made a prepayment at the beginning of a month that he can use, or he gets an invoice from Spreadshirt for all ordered products or articles at the end of the month for example. In this case, we assume that the partner operates his own checkout and that he collects the money from his customers.
  • Shipping: The shipping block allows to provide shipping information for order and order item. For the order, the shipping block contains the attributes shipping type, i.e. standard or express shipping in Europe, and shipping address.
    The shipping address can either be the partner’s address or in the white-label fulfillment case the customer’s address. Make sure that you send us the e-mail address of your service instead of the customer’s e-mail address for the white-label fulfillment case.
    For the order item, the shipping block right now only contains the shipping type with which the order item was actually shipped.
  • Billing: The billing block allows to provide a billing address that will be used  for billing.
  • Correlation: Correlation blocks can be provided for the order and all order items. By providing external order and order item ids, it is possible to connect the order and all order items of the Spreadshirt platform with the order and order items stored in the partners e-commerce or ERP system.
  • Attachments: Attachments can be provided for each order item. They allow to attach the product that shall be ordered with this order item and even links to images used in the product. That makes it possible to provide everything required to order a custom created product in one XML payload and with one HTTP request.
  • Errors: The error block contains all relevant information about errors that occured on processing the received order.

Creating Orders

According to our REST API’s resource types and their semantics, you can create an order by conducting a HTTP POST request on http://api.spreadshirt.net/api/v1/orders.

Minimum Order Payload

The minimum payload for creating an order would look as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
    <orderItems>
        <orderItem>
            <quantity>1</quantity>
            <element type="sprd:product"
                     xlink:href="http://api.spreadshirt.net/api/v1/shops/282267/products/23465816">
                <properties>
                    <property key="appearance">5</property>
                    <property key="size">4</property>
                </properties>
            </element>
        </orderItem>
    </orderItems>
    <payment>
        <type>EXTERNAL_FULFILLMENT</type>
    </payment>
    <shipping>
        <!-- standard or express shipping -->
        <shippingType id="1"/>
        <!-- mandatory -->
        <address type="private">
            <company>BITBOOST SYSTEMS</company>
            <!-- optional -->
            <person> <!-- do we need the details or is one line sufficient -->
                <salution id="1"/>
                <firstName>John</firstName>
                <lastName>Smith</lastName>
            </person>
            <street>E DRACHMAN</street>
            <houseNumber>421</houseNumber>
            <streetAnnex>Appartment 2</streetAnnex>
            <city>Los Angeles</city>
            <state code="CA">California</state>
            <!-- optional for USA etc. -->
            <country code="US">USA</country>
            <zipCode>85705</zipCode>
            <email>mbs@spreadshirt.net</email>
            <phone>+49 341 789 123</phone>
            <fax>+49 341 789 123</fax>
        </address>
    </shipping>
</order>

It contains one product as order item and the payment and shipping information that must at least be provided.

Additional Billing Address

Besides the shipping address one can also provide a different billing address as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
    <orderItems>
        <orderItem>
           ...
        </orderItem>
    </orderItems>
    <payment>
        ...
    </payment>
    <shipping>
        ...
    </shipping>
    <billing>             
      <address type="private">
         <company>BITBOOST SYSTEMS</company>
         <person>
            <salution id="1"/>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
         </person>
         <street>E DRACHMAN</street>
         <houseNumber>421</houseNumber>
         <streetAnnex>Appartment 2</streetAnnex>
         <city>Los Angeles</city>
         <state code="CA">California</state>
         <country code="US">USA</country>
         <zipCode>85705</zipCode>
         <email>mbs@spreadshirt.net</email>
         <phone>+49 999 888 777</phone>
         <fax>+49 999 888 777</fax>
      </address>   
   </billing>
</order>

Additional Correlation Information

For establishing a relationship between orders and order items from your e-commerce or ERP system with orders and order items from our platform, you can provide correlation information for order and order items as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
   <orderItems>
      <orderItem>
         ...
         <correlation>
            <partner>
               <orderItemId>ext-partner-order-item-123</orderItemId>
            </partner>
         </correlation>      
      </orderItem>        
   </orderItems>
   <payment>
       ...
   </payment>
   <shipping>
      ...
   </shipping>
   <billing>             
      ...    
   </billing>    
   <correlation>
      <partner>
         <orderId>ext-partner-order-123</orderId>
      </partner>
   </correlation>
</order>

Additional Attachments

Additional attachments can be provided per order item as illustrated in the order payload below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
   <orderItems>
      <orderItem>
         ...
         <correlation>
            ...
         </correlation>      
         <attachments>                        
            <attachment type="sprd:product" id="reference-1">
               <product>
                  <productType id="6"/>
                  <appearance id="1"/>
                  <restrictions>
                     <freeColorSelection>false</freeColorSelection>
                     <example>false</example>
                  </restrictions>
                  <configurations>
                     <configuration type="design">
                        <printArea id="4"/>
                        <printType id="17"/>
                        <offset unit="mm">
                           <x>60.0</x>
                           <y>70.0</y>
                        </offset>
                        <content dpi="25.4" unit="mm">
                           <svg>
                              <image transform="" width="200.025" height="194.945" designId="reference-2"/>
                           </svg>
                        </content>
                        <restrictions>
                           <changeable>false</changeable>
                        </restrictions>
                     </configuration>
                  </configurations>
               </product>
            </attachment>
            <attachment type="sprd:design" id="reference-2">
               <reference xlink:href="http://msa4.files.wordpress.com/2008/08/nyc-night1.jpg"/>
            </attachment>         
         </attachments>
      </orderItem>        
   </orderItems>
   <payment>
       ...
   </payment>
   <shipping>
      ...
   </shipping>
   <billing>             
      ...    
   </billing>    
   <correlation>
      ...
   </correlation>
</order>

Attachments allow you to provide the product payload and links to images of the product to be ordered with the actual order. That means you do not need to first create the product using the API and then the order but you can provide the product payload with the order. The product will then be created (and the provided designs be uploaded) automatically before the actual order is processed.

Retrieving Orders

Orders can be retrieved by either conducting a HTTP GET request on the order list http://api.spreadshirt.net/api/v1/orders?query=+partnerId:(1102730) with the right search query or by conducting a HTTP GET request on the order entity http://api.spreadshirt.net/api/v1/orders/1.

Minimum Order Payload

The minimum returned order payload will contain at least one order item and basic correlation, shipping and billing information.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net"
       xlink:href="http://api.spreadshirt.net/api/v1/orders/200001151" id="200001151">
    <shop xlink:href="http://api.spreadshirt.net/api/v1/shops/282267" id="282267"/>
    <orderItems>
        <orderItem xlink:href="http://api.spreadshirt.net/api/v1/orders/200001151/items/200001151"
                   id="200001151">
            <shop xlink:href="http://api.spreadshirt.net/api/v1/shops/282267" id="282267"/>                        
            <element id="23465816" type="sprd:product"
                     xlink:href="http://api.spreadshirt.net/api/v1/shops/282267/products/23465816">
                <properties>
                    <property key="appearance">5</property>
                    <property key="size">4</property>
                </properties>
            </element>  
            <fulfillmentState>ACCEPTED</fulfillmentState>
            <quantity>1</quantity>
            <price>
                <vatExcluded>13.90</vatExcluded>
                <vatIncluded>13.90</vatIncluded>
                <vat>0.00</vat>
                <currency id="1"/>
            </price>
            <created>2012-01-11T14:32:15+01:00</created>
            <modified>2012-01-11T14:32:28+01:00</modified>
        </orderItem>
    </orderItems>
    <correlation>
        <partner>
            <id>1102730</id>
        </partner>
    </correlation>
    <shipping>
        <shippingType id="1"/>
        <address type="private">
            <company>BITBOOST SYSTEMS</company>
            <person>
                <firstName>John</firstName>
                <lastName>Smith</lastName>
            </person>
            <street>E DRACHMAN</street>
            <houseNumber>421</houseNumber>
            <streetAnnex>Appartment 2</streetAnnex>
            <city>Los Angeles</city>
            <state code="CA"/>
            <country code="US"/>
            <zipCode>85705</zipCode>
            <email>mbs@spreadshirt.net</email>
            <phone>+49 341 789 123</phone>
            <fax>+49 341 789 123</fax>
        </address>
        <price>
            <vatExcluded>9.90</vatExcluded>
            <vatIncluded>9.90</vatIncluded>
            <vat>0.00</vat>
            <currency id="1"/>
        </price>
    </shipping>
    <billing>
        <address type="private">
            <company>BITBOOST SYSTEMS</company>
            <person>
                <firstName>John</firstName>
                <lastName>Smith</lastName>
            </person>
            <street>E DRACHMAN</street>
            <houseNumber>421</houseNumber>
            <streetAnnex>Appartment 2</streetAnnex>
            <city>Los Angeles</city>
            <state code="CA"/>
            <country code="US"/>
            <zipCode>85705</zipCode>
            <email>mbs@spreadshirt.net</email>
            <phone>+49 341 789 123</phone>
            <fax>+49 341 789 123</fax>
        </address>
    </billing>
    <created>2012-01-11T14:32:15+01:00</created>
    <modified>2012-01-11T14:32:28+01:00</modified>
</order>

Additional Correlation Information

If you have provided correlation information for order and order items, the order will also contain these information as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net"
       xlink:href="http://api.spreadshirt.net/api/v1/orders/200001151" id="200001151">
    ...
    <orderItems>
        <orderItem xlink:href="http://api.spreadshirt.net/api/v1/orders/200001151/items/200001151"
                   id="200001151">
            ... 
            <correlation>
               <partner>
                  <orderItemId>ext-partner-order-item-123</orderItemId>
               </partner>
            </correlation>                                  
            ...
        </orderItem>
    </orderItems>
    <correlation>
        <partner>
            <id>1102730</id>
            <orderId>ext-partner-order-123</orderId>        
        </partner>
    </correlation>
    ...
</order>

Additional Error Information

In case an error occurred during order processing, the order payload will contain the error information in an error block as follows.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
    <error>       
       <message>Product 23465816 does not exist or is not accessible!</message>    
    </error>     
    ...
    <orderItems>
        <orderItem>
            ...
        </orderItem>
    </orderItems>
    ...
</order>

Summary

In this blog post, I introduced the basics of our order model and told you how to retrieve and create orders using Spreadshirt API v1. With this knowledge, you should be able to write applications that make use of the new order API features. You can find more information about the mentioned order resources and order payload on our developer wiki.

Please also have a look at the other articles in the series “API Terminology Explained”:

One Reply to “The Order Model (API Terminology Explained #14)”

Comments are closed.