Order Model

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. However, the mechanism is extendable and will later allow to support articles from external partner as well.
A typical order, e.g. an order with one product, 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 dateCreated and dateModified 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 basket in a different appearance than the configured one.
    An order item also has two attributes dateCreated and dateModified 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 for example 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 you send as 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 external order item ids, it allows to connect the order and all order items 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 they will also contain these order 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>
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.