Order Resources

*Use https to make the calls described below.*

{excerpt}This document specifies the API for creating orders and working with order reports.

{color:#ff0000}{*}This feature (Order API) is not available for regular API partners\!*{color}
*It is solely reserved for big accounts who sell Spreadshirt articles on their own site and integrate Spreadshirt as the fulfiller for a couple of thousand orders per year.* When you are able to list external products on your shopping platform and capable of selling these numbers please [contact our sales team|mailto:sales@spreadshirt.net] .
{excerpt}

{toc:maxLevel=4}

- TODO: document transaction split scenarios

h1. Resources Order

h2. Retrieve Order List

Returns a list of orders for the given partnerId and the specified fulfillmentState.

|| Url | .../v1/orders ||
|| Sample | [http://api.spreadshirt.net/api/v1/orders] ||
|| Type | LIST ||
|| Method | GET ||
|| Request Parameters | ?query=...+partnerId\:(...) \+shopId\:(...) \+modified:\[.. TO ..\] \+processingState\:(...) \\
\\
*partnerId* \- id of partner we want to see orders for \\
*shopId* \- in case data for special shop is required only \\
*modified* \- all entries after, before or between given modified min and max \\
*processingState* \- RECEIVED, CREATED or ERROR \\ ||
|| Sort Parameters \\ | modified \\
created \\ ||
|| APIKey | true ||
|| SessionId | true ||

* for order request with query attribute without state statement, all orders except orders in state RECEIVED (in batch processing but not processed yet) will be returned
* in case orders that are in batch processing right now shall be returned, state RECEIVED needs to be given in query parameter
* userId for session restricts visible orders - means given partnerId needs to match session's userId

|| Use Case \\ || Query \\ || Example \\ ||
| *Partner orders* | {code}/orders?query=+partnerId:({partnerId}){code} | {code}/orders?query=+partnerId:(123){code} |
| *Partner orders for shop* | {code}/orders?query=+partnerId:({partnerId}) +shopId:({shopId}){code} | {code}/orders?query=+partnerId:(123) +shopId:(888){code} |
| *Partner orders modified in a specific timeframe* \\ | {code}/orders?query=+partnerId:({partnerId})
+modified:[{dateFrom} TO {dateTo}]
&sortOrder={asc/desc}&sortField=modified{code} \\ | {code}/orders?query=+partnerId:(123)
+modified:[2011-06-28T13:00:00 TO 2011-06-28T14:00:00]
&sortOrder=asc&sortField=modified{code} |
| *Partner orders that are in batch processing right now (asynchronously)* | {code}/orders?query=+partnerId:({partnerId})
+processingState:({processingState}){code} | {code}/orders?query=+partnerId:(123) +processingState:(RECEIVED){code} |

*Response Representation:*

{code}
<orders ...>
... see order representation below ...
</orders>
{code}

See [Order Representation|#Order]

Creates a single order on the platform. The given order items either link existing products or contain the product payload and might even contain links to images to be fetched before creating the product for the order item. Orders will always be created asynchronously.

|| Url | .../v1/orders ||
|| Sample | [http://api.spreadshirt.net/api/v1/orders] ||
|| Type | List ||
|| Method | POST ||
|| Special Status Codes | 201 Created ||
|| APIKey | true ||
|| SessionId | true ||

*Request Representation:*

{code}
<order ...>
... see order representation below ...
</order>
{code}

See [Order Representation|#Order]

Header:
{code}
Location: .../v1/orders/123
{code}

h3. Examples


h4. Order with Order Item that links existing Product

* shop id is the id of the shop you want to create the order item for
* quantity contains the number of items you want to order
* element type is sprd:product
* element id is a Spreadshirt product id, e.g. 23945182
* element xlink:href contains link to Spreadshirt product, e.g.&nbsp;[http://api.spreadshirt.net/api/v1/shops/205909/products/23945182]
* properties appearance and size contain valid appearance and size attribute from linked product type, e.g.&nbsp;[http://api.spreadshirt.net/api/v1/shops/205909/productTypes/6]
** appearance exists for product type
** size exists for product type
** stock state for appearance/size combination exists and is set to true (available)
** product.freeColorSelection == false \-> selected appearance is the one configured for the product
** product.freeColorSelection == true \-> selected appearance is one out of the defined ones for the product type
* correlation partner order item id contains the order item id of the partners order mgmt system

{code}
<order ...>
...
<orderItem>
<shop id="205909"/>
<quantity>1</quantity>
<element type="sprd:product"
xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/products/23945182">
<properties>
<property key="appearance">323</property>
<property key="size">5</property>
</properties>
</element>  
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
</orderItem>  
...
</order>
{code}

h4. Order with Order Item that links existing Article

* shop id is the id of the shop you want to create the order item for
* quantity contains the number of items you want to order
* element type is sprd:article
* element id is a Spreadshirt article id, e.g. 17106954
* element xlink:href contains link to Spreadshirt article, e.g.&nbsp;[http://api.spreadshirt.net/api/v1/shops/205909/articles/17106954]
* properties appearance and size contain valid appearance and size attribute from linked product type, e.g.&nbsp;[http://api.spreadshirt.net/api/v1/shops/205909/productTypes/6]
** appearance exists for product type
** size exists for product type
** stock state for appearance/size combination exists and is set to true (available)
** product.freeColorSelection == false \-> selected appearance is the one configured for the product
** product.freeColorSelection == true \-> selected appearance is one out of the defined ones for the product type
* correlation partner order item id contains the order item id of the partners order mgmt system

{code}
<order ...>
...  
<orderItem>
<quantity>1</quantity>
<element type="sprd:article"   
xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/articles/17106954">
<properties>
<property key="appearance">323</property>
<property key="size">5</property>
</properties>
</element>  
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
</orderItem>  
... 
</order>
{code}

h4. Order with Order Item that links Product provided with Attachment

* shop id is the id of the shop you want to create the order item for
* quantity contains the number of items you want to order
* element type is sprd:product
* element id is the id of the attachment that contains the product payload for the product to be created for this order item, e.g. reference-1
* properties appearance and size contain valid appearance and size attribute from linked product type, e.g.&nbsp;[http://api.spreadshirt.net/api/v1/shops/205909/productTypes/95]
** appearance exists for product type
** size exists for product type
** stock state for appearance/size combination exists and is set to true (available)
** product.freeColorSelection == false \-> selected appearance is the one configured for the product
** product.freeColorSelection == true \-> selected appearance is one out of the defined ones for the product type
* correlation partner order item id contains the order item id of the partners order mgmt system
* attachment contains the product payload for the product that will be created for this order item

{code}
<order ...>
...
<orderItem ...>
<quantity>1</quantity>
<element type="sprd:product" xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/products/reference-1">
<properties>
<property key="appearance">2</property>
<property key="size">5</property>
</properties>
</element>  
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
<attachments>
<attachment id="reference-1" type="sprd:product">
<product xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://api.spreadshirt.net">
<productType id="95"/>
<appearance id="2"/>
<restrictions>
<freeColorSelection>false</freeColorSelection>
<example>false</example>
</restrictions>
<configurations>
<configuration type="text">
<printArea id="154"/>
<printType id="14"/>
<offset unit="mm">
<x>20.0</x>
<y>20.0</y>
</offset>
<content dpi="25.4" unit="mm">
<svg>
<text transform="" font-style="normal" font-size="36"
font-weight="normal" font-family="BelloScript"
text-anchor="start" y="110" x="1" printColorId="12">
<tspan>Heidi</tspan>
</text>
</svg>
</content>
<restrictions>
<changeable>false</changeable>
</restrictions>
</configuration>
</configurations>
</product>         
</attachment>
</attachments>
</orderItem>
...
</order>
{code}

h4. Order with Order Item that links Product and Design provided with Attachment

* shop id is the id of the shop you want to create the order item for
* quantity contains the number of items you want to order
* element type is sprd:product
* element id is the id of the attachment that contains the product payload for the product to be created for this order item, e.g. reference-1
* properties appearance and size contain valid appearance and size attribute from linked product type, e.g.&nbsp;[http://api.spreadshirt.net/api/v1/shops/205909/productTypes/95]
** appearance exists for product type
** size exists for product type
** stock state for appearance/size combination exists and is set to true (available)
** product.freeColorSelection == false \-> selected appearance is the one configured for the product
** product.freeColorSelection == true \-> selected appearance is one out of the defined ones for the product type
* correlation partner order item id contains the order item id of the partners order mgmt system
* attachment contains the product payload for the product that will be created for this order item, i.e. attachment with id reference-1
* product configuration in attachment reference-1 links the design provided with attachment reference-2 that will be created automatically for this order item before the product is created
* second attachment contains a link to an image that will be fetched by our image API to create the required design, i.e. attachment with id reference-2

{code}
<order ...>
...
<orderItem ...>
<quantity>1</quantity>
<element type="sprd:product" xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/products/reference-1">
<properties>
<property key="appearance">2</property>
<property key="size">5</property>
</properties>
</element>  
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
<attachments>
<attachment type="sprd:product" id="reference-1">
<product>
<productType id="6"/>
<appearance id="2"/>
<restrictions>
<freeColorSelection>false</freeColorSelection>
<example>false</example>
</restrictions>
<configurations>
<configuration type="design">
<printArea id="4"/>
<printType id="2"/>
<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"
printColorIds="1" 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://picasaweb.google.com/images/123"/>
</attachment>
</attachments>
</orderItem>
...
</order>
{code}

h2. Create Orders (Batch Order)

Creates one or multiple orders on the platform. The given order items either link existing products or contain the product payload and might even contain links to images to be fetched before creating the product for the order item. Batch orders are always processed asynchronously.

|| Url | .../v1/orders ||
|| Sample | [http://api.spreadshirt.net/api/v1/orders] ||
|| Type | LIST ||
|| Method | POST ||
|| Special Status Codes | 200 OK ||
|| APIKey | true ||
|| SessionId | true ||

*Request Representation:*

{code}
<orders ...>
<order ...>
... see order representation below ...
</order>
...
</orders>
{code}

See [Order Representation|#Order]

{code}
<references>
<reference xlink:href=".../v1/orders/123" id="123"/>
<reference xlink:href=".../v1/orders/456" id="456"/>
...
</references>
{code}

h3. Examples

h4. Multiple Order Items in a Batch Order

{code}
<order ...>
...
<orderItem>
<quantity>1</quantity>
<element type="sprd:product"
xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/products/23945182">
<properties>
<property key="appearance">323</property>
<property key="size">5</property>
</properties>
</element>  
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
</orderItem>  
<orderItem>
<quantity>1</quantity>
<element type="sprd:product"
xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/products/9579484">
<properties>
<property key="appearance">248</property>
<property key="size">4</property>
</properties>
</element>  
<correlation>
<partner>
<orderItemId>extshop-0000000002</orderItemId>
</partner>
</correlation>
</orderItem>  
...
</order>
{code}

h2. Retrieve Order

Retrieve the order for the given order id.

|| Url | .../v1/orders/\{orderId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/orders/123|http://api.spreadshirt.net/api/v1/orders/123] ||
|| Type | ENTITY ||
|| Method | GET ||
|| APIKey | true ||
|| SessionId | true ||

*Response Representation:*
{code}
<order ...>
... see order representation below ...
</order>
{code}

See [Order Representation|#Order]

|| Url | .../v1/orders/\{orderId\}/items ||
|| Sample | [http://api.spreadshirt.net/api/v1/orders/123/items|http://api.spreadshirt.net/api/v1/orders/123/items] ||
|| Type | LIST ||
|| Method | GET ||
|| APIKey | true ||
|| SessionId | true ||

*Response Representation:*
{code}
<orderItems>
<orderItem ...>
... see order item representation below ...
</orderItem>
</orderItems>
{code}

See [Order Item Representation|#Order Item]

|| Url | .../v1/orders/\{orderId\}/items/\{orderItemId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/orders/123/items/1|http://api.spreadshirt.net/api/v1/orders/123/items/1] ||
|| Type | ENTITY ||
|| Method | GET ||
|| APIKey | true ||
|| SessionId | true ||

*Response Representation:*
{code}
<orderItem ...>
... see order item representation below ...
</orderItem>
{code}

See [Order Item Representation|#Order Item]

|| Url | .../v1/orderReports ||
|| Sample | [http://api.spreadshirt.net/api/v1/orderReports] ||
|| Type | LIST ||
|| Method | GET ||
|| Request Parameters | ?query=+partnerId:-( ...) \+state:-( ...) \\
\\
*partnerId* \- id of partner we want to see orders for \\
*state* \- report states are ACTIVATED, DELETED (report marked as read) \\ ||
|| APIKey | true ||
|| SessionId | true ||

*Response Representation:*

{code}
<orderReports ...>
... see order report representation below ...
</orderReports>
{code}

See [Order Report Representation|#OrderReport]

|| Url | .../v1/orderReports/\{reportId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/orderReports/123] ||
|| Type | ENTITY ||
|| Method | GET ||
|| APIKey | true ||
|| SessionId | true ||

*Response Representation:*

{code}
<orderReport ...>
... see order report representation below ...
</orderReport>
{code}

See [Order Report Representation|#OrderReport]

|| Url | .../v1/orderReports/\{reportId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/orderReports/123] ||
|| Type | ENTITY ||
|| Method | DELETE ||
|| APIKey | true ||
|| SessionId | true ||

h2. Adjust Orders

This resource allows to send order adjustments to Spreadshirt, for example in order to cancel an order or single order items.&nbsp;

|| Url | .../v1/orderAdjustments ||
|| Sample | [http://api.spreadshirt.net/api/v1/orderAdjustments|http://api.spreadshirt.net/api/v1/orderAdjustments] ||
|| Type | LIST ||
|| Method | POST ||
|| Special Status Codes | 200 ||
|| APIKey | true ||
|| SessionId | true ||

Payload:

{code}
<orderAdjustments>
...
</orderAdjustments>
{code}

h2. Order

|| Field || Mandatory in Read Payload || Mandatory in Write Payload || Description \\ ||
| order \\ | x | x | Order represents a set of order items, i.e. products or articles, a customer or partner ordered at Spreadshirt. \\ |
| order/shop \\ | x | | Reference to the shop, where the customer ordered the items. \\ |
| order/orderItems | x | x | List of order items that belong to this order. \\ |
| order/orderItems/orderItem | x | x | See [Order Item Representation|#Order Item] |
| order/correlation \\ | x | x | Correlation information that is required to correlate partner data with Spreadshirt's platform data, e.g. partner orderId with our orderId. \\ |
| order/correlation/partner \\ | x | x | Partner correlation block. \\ |
| order/correlation/partner/id \\ | x | x | Partner id. \\ |
| order/correlation/partner/orderId \\ | x | x | Id of order in partner's software system. Provide an order id from your system to be able to track your order correctly. \\ |
| order/payment \\ | | x | Payment information that defines how customer payed for order. \\ |
| order/payment/type&nbsp; \\ | | x | Defines the used payment type. Use EXTERNAL_FULFILLMENT for white label fulfillment cases. |
| order/shipping \\ | x | x | Shipping information that defines to which address and with which parcel service the order needs to be shipped. \\ |
| order/shipping/shippingType \\ | x | x | Reference to a valid shipping type. \\ |
| order/shipping/parcelDeliveries | | | List of parcel deliveries connected to this order. |
| order/shipping/parcelDeliveries/parcelDelivery | | | One parcel delivery. |
| order/shipping/parcelDeliveries/parcelDelivery/parcels \\ | | | List of parcels connected to a delivery. |
| order/shipping/parcelDeliveries/parcelDelivery/parcels/parcel \\ | | | One concrete parcel. |
| order/shipping/parcelDeliveries/parcelDelivery/parcels/parcel/shippingType \\ | | | The actual shipping type used for this parcel, e.g. customer wanted standard shipping but we send it with express shipping because production took longer than expected. |
| order/shipping/parcelDeliveries/parcelDelivery/parcels/parcel/trackingCode \\ | | | The tracking code of the parcel that can be used to track parcel delivery. |
| order/shipping/parcelDeliveries/parcelDelivery/parcels/parcel/trackingLink \\ | | | A link to the web site of the shipping carrier that can be used to track parcel delivery. |
| order/shipping/parcelDeliveries/parcelDelivery/parcels/parcel/shipped \\ | | | Date when we shipped the parcel, i.e. gave it to the shipping carrier. |

| order/modified \\ | x | | Date of last order modification. \\ |
| order/errors | | | List of errors that occured. |
| order/errors/error | | | Single error details |
| order/errors/error/message | | | Error message. |

*Read Example:*

{code:xml}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink"  
xmlns="http://api.spreadshirt.net"  
id="...">
<shop id="..."/>
  <orderItems>
... see order item read payload below ...
</orderItems>
<correlation>
<!-- area for correlation info -->
<partner>
<id>...</id>
<orderId>...</orderId>
</partner>
</correlation>
<shipping>
<!-- standard or express shipping -->
<shippingType id="1"/>

<parcelDeliveries>
<parcelDelivery id="200001701">
<parcels>
<parcel id="123">
<shippingType id="1"/>
<trackingCode>55 55 5</trackingCode>
<trackingLink xlink:href="http://post.de?idc=55 55 5"/>
<shipped>2012-02-10T00:00:00+01:00</shipped>
</parcel>
</parcels>
</parcelDelivery> ...
</parcelDeliveries>

<!-- mandatory -->
<address ...>
... see address payload below ...
</address>
<price>
...
</price>
</shipping>
<billing>
<!-- optional -->
<address ...>
... see address payload below ...
</address>
</billing>
...
</order>
{code}

*Write Example:*

{code:xml}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order xmlns:xlink="http://www.w3.org/1999/xlink"  
xmlns="http://api.spreadshirt.net">  
<shop id="..."/>
  <orderItems>
... see order item write payload below ...
</orderItems>
<correlation>
<!-- area for correlation info -->
<partner>
<id>...</id>
<orderId>...</orderId>
</partner>
</correlation>
<payment>
<type>EXTERNAL_FULFILLMENT</type>
</payment>
<shipping>
<!-- standard or express shipping -->
<shippingType id="1"/>  

<!-- mandatory -->
<address ...>
... see address payload below ...
</address>
<price>
...
</price>
</shipping>
<billing>
<!-- optional -->
<address ...>
... see address payload below ...
</address>
</billing>
...
</order>
{code}

h2. OrderItem

|| Field || Mandatory in Read Payload || Mandatory in Write Payload || Description ||
| orderItem | x | x | Contents for a single order item. \\ |
| orderItem/shop | x | | Reference to the shop where the order item element belongs to. \\ |
| orderItem/quantity | x | x | {color:#333333}The number of items the customer wants to buy. Is always an int > 0.{color}\\ |
| orderItem/created | x | | Date of order item creation. \\ |
| orderItem/modified | x | | Date of last order item modification. \\ |
| orderItem/price | x | | {color:#333333}The single order item price.{color} \\ |
| orderItem/fulfillmentState | x | | The actual fulfillmentState of the order item. See fulfillment states below for further information. \\ |
| orderItem/element | x | x | {color:#333333}The abstract element that customer bought.{color} \\ |
| orderItem/element/@id | x | x | {color:#333333}The id of the abstract thing the customer bought. Allowed right now are Spreadshirt article id and product ids. Will be set automatically on order item creation.{color}{color:#333333}&nbsp;{color} \\ |
| orderItem/element/@type | x | x | {color:#333333}The actual type of the abstract element which makes it to a concrete one. Can be{color}{color:#333333}&nbsp;{color}{color:#333333}{_}sprd:article{_}{color} {color:#333333}or{color}{color:#333333}&nbsp;{color}{color:#333333}{_}sprd:product{_}{color}{color:#333333}&nbsp;{color}{color:#333333}for Spreadshirt articles or products right now. Type is mandatory for order item creations.{color}{color:#333333}&nbsp;{color} \\ |
| orderItem/element/@xlink:href | x | x | {color:#333333}A link to the actual concrete element you added to the order. Can be either a link to a Spreadshirt article or product right now (see{color}[Retrieve Product|https://developer.spreadshirt.net/display/API/Product+Resources#ProductResources-RetrieveShopProductEntity]{color:#333333}&nbsp;{color}{color:#333333}and{color}{color:#333333}&nbsp;{color}[Retrieve Article|https://developer.spreadshirt.net/display/API/Product+Resources#ProductResources-RetrieveShopArticleEntity]{color:#333333}&nbsp;{color}{color:#333333}). This attribute is mandatory for order item creations.{color}{color:#333333}&nbsp;{color} \\ |
| orderItem/element/properties | x | x | {color:#333333}A list of properties that further refine the abstract element.{color}{color:#333333}&nbsp;{color} \\ |
| orderItem/element/properties/property | x | x | {color:#333333}A property value that corresponds to the property key, e.g. size:2 or appearance:1. Properties might be different depending on the element type. Spreadshirt articles and products support size and appearance only. Properties are mandatory for order item creations.{color}{color:#333333}&nbsp;{color} \\ |
| orderItem/element/properties/property/@key | x | x | |
| orderItem/correlation | x | x | Correlation information that is required to correlate partner data with Spreadshirt's platform data, e.g. partner order item id with our order item id. \\ |
| orderItem/correlation/partner | x | x | Partner correlation block. \\ |
| orderItem/correlation/partner/orderItemId | x | x | Id of the order item in partner's software system. Provide an order item id from your system to be able to track your order item correctly. \\ |
| orderItem/shipping | x | x | Shipping information for the order item. \\ |
| orderItem/shipping/parcelDelivery | | | Reference to the actual parcel delivery, that contains the shipping type and tracking code. |
| orderItem/attachments \\ | | x | Any attachments, e.g. design data or product xml, that come with the order and need to be created before order processing. \\ |
| orderItem/attachments/attachment \\ | | x | One order attachment. \\ |
| orderItem/attachments/attachment/@type \\ | | x | Type of the order attachment, e.g. sprd:design - for design data that needs to be uploaded, sprd:product - for product xml for which product needs to be created. \\ |
| orderItem/attachments/attachment/@id \\ | | x | Id of the attachment, i.e. the element wrapped by the attachment, that can be used to link wrapped element, e.g. product payload links attachment that contains required design. \\ |

*Read Example:*

{code:xml}
<orderItem id="..." xlink:href="..." transactionId="123">
<shop id="..."/>
<quantity>2</quantity>
...
<created>...</created>
<modified>...</modified>
<!-- link existing product or article or product from attachment -->
<element id="456" type="sprd:product" xlink:href="http://api.spreadshirt.net/v1/shops/42/products/456">
<properties>
<property key="appearance">15</property>
<property key="size">12</property>
</properties>
</element>
<price>
...
</price>

<fulfillmentState>created</fulfillmentState>

<correlation>
<!-- area for correlation info -->
<partner>
<orderItemId>...</orderItemId>
</partner>
  </correlation>

<shipping>
<parcelDelivery id="200001701"/>
</shipping>
</orderItem>
{code}

*Write Example:*

{code:xml}
<orderItem> 
   <quantity>1</quantity>
   <element type="sprd:product"
           xlink:href="http://localhost:8080/api/v1/shops/205909/products/reference-1">
  <properties>
      <property key="appearance">2</property>
         <property key="size">3</property>
      </properties>
   </element>
   <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>
{code}

h2. Address

|| Field \\ || Description \\ ||
| address \\ | Address we want to ship items to or send the bill. \\ |
| address/@type \\ | Address type, e.g. private or packstation. \\ |
| address/company \\ | Name of the company or null. \\ |
| address/person \\ | Person we ship to. \\ |
| address/person/salutation \\ | Salutation of the person. \\ |
| address/person/salutation/@id | Mr. 1, Mrs. 2, Ms. 3, Company 4 |
| address/person/firstName \\ | First name of the person. \\ |
| address/person/lastName \\ | Last name of the person. \\ |
| address/street \\ | Name of the street, e.g. E Drachman. \\ |
| address/houseNumber \\ | House number in the street, e.g. 421. \\ |
| address/streetAnnex \\ | Any additional street information, e.g. Appartment 2. \\ |
| address/city \\ | City person lives in, e.g. Los Angeles. \\ |
| address/state \\ | State the city is located, e.g. California. \\ |
| address/state/@code \\ | Iso state code. \\ |
| address/country \\ | Country the state is located, e.g. USA. \\ |
| address/country/@code \\ | Iso country code. \\ |
| address/zipCode \\ | Zip code. \\ |
| address/email \\ | E-mail address that can be used to contact person. \\ |
| address/phone \\ | Phone number that can be used to contact person. \\ |
| address/fax \\ | Fax number that can be used to contact person. \\ |
*Example:*
{code:xml}
<address type="private/packstation">
<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 ...</phone>
<fax>+49 ...</fax>
</address>
{code}

h2. Processing States



!API Order Processing States.jpg|border=1!
Processing states are as follows:
|| State || Description ||
| Received \\ | Received order with order items but did not create order in platform yet. State is required for order items as we support asynchronous reception of orders. These orders will be stored as unprocessed orders and the order items will be displayed to the API caller as items in state received. |
| Created | |
| Error | |

State transitions are as follows:
|| Current State || Next State || Description ||
| Received | Created | |
| Received | Error | |

h2. Fulfillment States

!API Order States.jpg|border=1!
The description of the states displayed above is as follows:

|| State \\ || Description \\ ||
| Created \\ | Created order in platform. For asynchronously received orders, this is the state after the unprocessed order was converted into a order. For synchronously received orders, this is the first state. \\ |
| Accepted \\ | We accepted the order and are willing to produce and ship the order items to the customer. This is in general the case if required product types are in stock, shipping address is valid, etc.. \\ |
| Waiting for Customer | Customer input is required, before Spreadshirt can continue to process order item. |
| In Progress \\ | Order item (product) is in production. \\ |
| Shipped \\ | Order item (product) is produced and shipped to the customer. \\ |
| Returned \\ | Customer returned order item (product) \\ |
| Canceled \\ | Order item was canceled. \\
Possible reasons are: \\
* Design upload failed
* Product creation failed
* Customer canceled
* No inventory
* Price error
* Product out of stock
* Customer address incorrect
* Risk assessment information not valid
* Payment error
* Production failed
* Could not ship
* Shipment not received |

The state transitions can be described as follows:
|| Current State \\ || Next State \\ || Description \\ ||
| Created \\ | Accepted \\ | Accept order item, which means we are able and willing to produce and shop order item (product). \\ |
| Accepted | Waiting for Customer | Customer input is required, e.g. t-shirt is no longer available in color. |
| Waiting for Customer | Accepted | Customer input provided, e.g.customer accepts different t-shirt. |
| Waiting for Customer | Canceled | Customer canceled order item, e.g. customer declines different t-shirt. |
| Accepted \\ | In Progress \\ | Start production of order item (product). \\ |
| In Progress \\ | Shipped \\ | Finished production of order item and shipped it to customer. \\ |
| Shipped \\ | Returned \\ | Customer returned order item to us. \\ |
| Returned \\ | Accepted \\ | Reproduce order item (product). \\ |
| Created \\ | Canceled \\ | Reject order item \\
* Design upload failed (for orders with design attachment)
* Product creation failed (for orders with product attachment)\* No inventory
* Price error
* Product out of stock
* Customer address incorrect
* Risk assessment information not valid (customer area willingness to pay rating)
* Payment error |
| Accepted \\ | Canceled \\ | Canceled order item \\
* Customer canceled |
| In Progess \\ | Canceled \\ | Reject order item \\
* No inventory
* Product out of stock
* Production failed
* Could not ship |
| In Progress | Waiting for Customer | Customer input is required, e.g. design is to big for the t-shirt to be produced. \\ |
| Shipped \\ | Canceled \\ | Reject order item \\
* Shipment not received |
| Returned \\ | Canceled \\ | Canceled order item \\
* Customer canceled \\
Reject order item \\
* Production canceled |

Descriptions for the possible cancel reasons are as follows:
|| Cancel Reason \\ || Description \\ ||
| Design upload failed \\ | Design provided with order item attachment could not be uploaded. \\ |
| Product creation failed \\ | Product provided with order item attachment could not be created. \\ |
| Customer canceled | Customer canceled order with all order items \\ |
| No inventory \\ | No inventory for producing order item on-demand available. \\ |
| Price error \\ | Given order item price does not match calculated order item price. \\ |
| Product out of stock \\ | Preproduced product is no longer available. \\ |
| Customer address incorrect \\ | Customer address is invalid. \\ |
| Risk assessment information not valid \\ | Customer credit rating is bad. \\ |
| Payment error \\ | Payment did not work. \\ |
| Production failed \\ | Production of order item failed and can not are shall not be reproduced. \\ |
| Could not ship \\ | Could not ship item to customer. \\ |
| Shipment not received \\ | Customer did not receive item. \\ |

h2. OrderReport

|| Field \\ || Description \\ ||
| orderReport \\ | Order report that contains all order item modifications of the partner's orders since last order report generation.&nbsp; \\ |
| orderReport/orderItemModifications \\ | List of order item modifications \\ |
| orderReport/orderItemModifications/orderItemModification \\ | Order item modification. \\ |
| orderReport/orderItemModifications/orderItemModification/order \\ | Reference to the order the referenced order item belongs to. \\ |
| orderReport/orderItemModifications/orderItemModification/orderItem | Reference to the order item that was modified. \\ |
| orderReport/orderItemModifications/orderItemModification/correlation \\ | Correlation information that is required to correlate partner data with Spreadshirt's platform data, e.g. partner order item id with our order item id.&nbsp; \\ |
| orderReport/orderItemModifications/orderItemModification/correlation/partner \\ | Partner correlation block.&nbsp; \\ |
| orderReport/orderItemModifications/orderItemModification/correlation/partner/orderItemId \\ | Id of the order item in partner's software system.&nbsp; \\ |
| orderReport/orderItemModifications/orderItemModification/fulfillmentState \\ | Fulfillment state of the order item after modification (see fulfillment states below). \\ |
| orderReport/orderItemModifications/orderItemModification/modified | Date of modification. \\ |
| orderReport/state \\ | Processing state of order report, e.g. activated, deleted (processed). \\ |
| orderReport/created \\ | Date of report creation. \\ |
| orderReport/modified \\ | Date of last report modification (state change). \\ |

*Example:*
{code:xml}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orderReport xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://api.spreadshirt.net" 
id="123" href="http://api.spreadshirt.net/api/v1/orderReports/123">
<orderItemModifications>
<orderItemModification>
<order id="123" xlink:href="http://api.spreadshirt.net/api/v1/orders/123"/>
<orderItem id="456"/>
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
<fulfillmentState>RECEIVED</fulfillmentState>
<modified>2011-08-03 08:14:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
<orderItemModification>
<order id="123" xlink:href="http://api.spreadshirt.net/api/v1/orders/123"/>
<orderItem id="456"/>
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
<fulfillmentState>CREATED</fulfillmentState>
<modified>2011-08-03 08:15:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
<orderItemModification>
<order id="123" xlink:href="http://api.spreadshirt.net/api/v1/orders/123"/>
<orderItem id="456"/>
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
<fulfillmentState>ACCEPTED</fulfillmentState>
<modified>2011-08-03 08:30:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
<orderItemModification>
<order id="123" xlink:href="http://api.spreadshirt.net/api/v1/orders/123"/>
<orderItem id="456"/>
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
<fulfillmentState>IN_PROGRESS</fulfillmentState>
<modified>2011-08-03 12:00:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
<orderItemModification>
<order id="123" xlink:href="http://api.spreadshirt.net/api/v1/orders/123"/>
<orderItem id="456"/>
<correlation>
<partner>
<orderItemId>extshop-0000000001</orderItemId>
</partner>
</correlation>
<fulfillmentState>SHIPPED</fulfillmentState>
<modified>2011-08-03 17:00:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
</orderItemModifications>
<state>ACTIVATED</state>
<created>2011-08-20 20:00:00</created>
<modified>2011-08-20 20:00:00</modified>
</orderReport>
{code}

h2. OrderAdjustment

|| Field || Description ||
| orderAdjustment | Representation of a platform order adjustment. |
| orderAdjustment/order | Reference to the order to be adjusted. |
| orderAdjustment/fulfillmentState | The new fulfillment state, e.g. CANCELED in case the order shall be canceled. |
| orderAdjustment/orderItemAdjustments | Optional list of order item adjustments, in case single items of the order shall be adjusted. |
| orderAdjustment/orderItemAdjustments/orderItemAdjustment | A single order item adjustment. |
| orderAdjustment/orderItemAdjustments/orderItemAdjustment/orderItem | Reference to the order item to be adjusted. |
| orderAdjustment/orderItemAdjustments/orderItemAdjustment/fulfillmentState | The new fulfillment state, e.g. CANCELED in case the order item shall be canceled. |
Example:

{code}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orderAdjustment xmlns:xlink="http://www.w3.org/1999/xlink"  
xmlns="http://api.spreadshirt.net">  
<order id="123" xlink:href="http://api.spreadshirt.net/api/v1/orders/123"/>
<fulfillmentState>CANCELED</fulfillmentState>
<orderItemAdjustments>
<orderItemAdjustment>
<orderItem id="456" xlink:href="http://api.spreadshirt.net/api/v1/orders/123/items/456"/>
<fulfillmentState>CANCELED</fulfillmentState>
</orderItemAdjustment>
<orderItemAdjustments>
</orderAdjustment>
{code}