Solution Guide - External Platform uses Spreadshirt as Fulfillment Platform

{toc}

h3. Summary

* External platform is a photo community, a merchandise platform or a cross-selling application managed by an external partner (probably you)
* External platform can have prices different from the Spreadshirt product prices
* Customers buy their items at the external platform and interact with external platform only
* Spreadshirt is fulfillment partner means that Spreadshirt does white label fulfillment for the partner only
** Spreadshirt has no customer contact
** Spreadshirt accepts pixel designs (png, gif, jpg) for simplicity (vector designs are also possible, but they can not instantly be used for product creation)
** Spreadshirt does not provide the checkout and only receives orders from external partner
** Orders are all ordered on the partners user account (Spreadshirt does not now customers and does not have customer accounts or data) but with the customers address (Spreadshirt produces and ships the items)
** Order e-mail address is always the partner e-mail address not the customer e-mail address, so Spreadshirt order tracking e-mails are sent to partners e-mail address
** Spreadshirt produces and ships items based on orders from external partner
** Spreadshirt produces the items either based on prepayment or based on weekly or monthly invoice
** Spreadshirt charges the money from the partner that ordered the items not from the customer (\!) based on the price structure configured for the partners Spreadshirt shop
** Spreadshirt does white label fulfillment, so we send the ordered items to the address given by the external partner - which usually is the customer address 

h3. Example

Let's say we have a partner that operates a photo community. The community works quite simple: photographers can open their own space on the photo community and upload their favorite photos. They can also create t-shirts with these photos. All community members can browse the different spaces of all photographers. They can vote for different photos and they are able to buy either a poster of that photo or a t-shirt with that photo. They can add the posters and t-shirts to the communities basket and use the communities checkout to actually order the item from the partner that opperates the community. However, the partner does not actually produce the poster or the t-shirts himself, but he uses external white label fulfillers to have them produced and shipped to the customers. So, if the customer orders the items at the partner, the partner himself actually sends an order to the white label fulfiller for the particular item - which is Spreadshirt in this scenario for the t-shirts. Additionally, the partner informs his customer about order shipping based on the order state changes of the fulfiller's orders.

h4. Preliminaries

* Partner has account with Spreadshirt (Spreadshirt user id) - in our scenario, we assume user has id 123
* Partner has one designer shop with Spreadshirt (Spreadshirt shop id) - in our scenario, we assume shop has id 321
* Partner account is configured for white label fulfillment and access to order API (contracts are signed, etc. - ask sales for more details)

h4. Use Cases relevant for Integration Scenario with Spreadshirt

# Photographer creates t-shirt with his photo in his community space
# Customer buys a t-shirt in the photo community
# Partner sends order shipping notification to customer

h5. Photographer creates T-Shirt with his Photo in his Community Space

!solution_guide_photo_community-use_case-create_product.png|border=1!

h6. 1. Photographer creates Product (T-Shirt)

We assume that the partner has a simple photo product creator application up and running and that is able to [upload designs|API:Uploading Designs to Spreadshirt using Spreadshirt API v1] and [create products with Spreadshirt|API:Creating Products on Spreadshirt using Spreadshirt API v1]. The application should work similar to [Spreadshirt's Confomat 7|http://www.spreadshirt.de/t-shirt-gestalten-und-bedrucken-C59] or [Spreadshirt's Simplomat demo|API:Simplomat (Simple Shirt Designer Demo)]. When the photo product creator creates a new product with that photo in the photo community, it will 

1.1. Create a new design data entity for the photo with Spreadshirt
1.2. Upload the design to Spreadshirt (a link to the photo that exists in the photo community already)
1.3. Create a new product with Spreadshirt
1.4. Create a product entity in the photo community that contains the product data relevant for the photo community and a link to the actual Spreadshirt product

h6. 1.1. Create Design Entity

Photo Product Creator create the required design entity with Spreadshirt that contains the design meta data. Spreadshirt Data API returns a link to the location of the design entity and the design id.

*HTTP Request:*

*URL:* POST [http://api.spreadshirt.net/api/v1/users/123/designs]

{code}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<design xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
<name>Photo Community - xy Design</name>
<description>Photo Community - xy Design</description>
</design>
{code}

*HTTP Response:*

*Location:* [http://api.spreadshirt.net/api/v1/users/123/designs/456]

h6. 1.2. Upload Design

Photo Product Creator uploads the actual photo to Spreadshirt using Spreadshirt's image API. Thereby, the Photo Product Creator sends the Spreadshirt image API a pointer to the actual image. Spreadshirt's image API then downloads the image from the given location.

*HTTP Request:*

*URL:* PUT&nbsp;[http://image.spreadshirt.net/api/v1/designs/u456]?mediaType=xml





*Payload:&nbsp;*
{code}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reference xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net" 
xlink:href="http://photo.community.virtual/photographer/789/images/1011"/>
{code}

*HTTP Response:*

*Status:* 200 (OK)

h6. 1.2.1. Download Design

Image server downloads the image from the photo community and stores it as a Spreadshirt design.

*HTTP Request:*

*URL:* GET [http://photo.community.virtual/photographer/789/images/1011]

Photo Product Creator creates a product with the design with Spreadshirt.

*HTTP Request:*

*URL:* POST [http://api.spreadshirt.net/api/v1/users/123/products]

{code}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<product xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
<name>Männer T-Shirt klassisch</name>
<user id="123"/>
<productType id="6"/>
<appearance id="1"/>
<configurations>
<configuration type="design">
<printArea id="4"/>
<printType id="17"/>
<offset unit="mm">
<x>46.086</x>
<y>55.021</y>
</offset>
<content dpi="25.4" unit="mm">
<svg viewBox="0 0 216.747 162.56">
<image height="162.56" width="216.747" printColorRGBs="" designId="u456"/>
</svg>
</content>
</configuration>
</configurations>
</product>
{code}
*HTTP Response:*

*Location:* [http://api.spreadshirt.net/api/v1/users/123/products/789]

The product is now also available in the user's shop at&nbsp;[http://api.spreadshirt.net/api/v1/shops/321/products/789|http://api.spreadshirt.net/api/v1/users/123/products/789]. You need the shop product URL later to be able to place the order.

h6. 1.4. Create Product for the Photo Community

Photo Product Creator stores "Product with Photo" entity in the Photo Communities database that also contains the id of and a link to the product created with Spreadshirt. This id and the link is later required to actually place the order with Spreadshirt. So the partner store the following data in his product entity:&nbsp;

*Product with Photo Entity*

|| Field || Value || Description ||
| id | 1 | id of the product in the photo community |
| name | ... | photographers name for the product in the photo community \\ |
| description | ... | photographers description for the product in the photo community \\ |
| category | | photo community category the photographer put his product in \\ |
| image | [http://image.spreadshirt.net/image-server/v1/products/789/views/1] | product image |
| price | 20.00 € | partner price not Spreadshirt price \\ |
| externalProductId | 789 | Spreadshirt product id |
| externalProductLink | +[+http://api.spreadshirt.net/api/v1/shops/321/products/789+|http://api.spreadshirt.net/api/v1/users/123/products/789]+ \\ | Spreadshirt product link |

h6. Further Reading

* [API:Design Model]
* [API:ProductType Model]
* [API:Print Type Model]
* [API:Font Model]
* [API:Product Model]
* [API:Uploading Designs to Spreadshirt using Spreadshirt API v1]
* [API:Creating Products on Spreadshirt using Spreadshirt API v1]
* [API:Text and Design Positioning Guide]
* [API:Mapping Coordinates from Spreadshirt's SVG User Coordinate System to your Application's Coordinate System]
* [API:Inventory Resources]
* [API:Design Resources]
* [API:Product Resources]

h5. Customer buys a T-Shirt at the Photo Community

!solution_guide_photo_community-use_case-buy_product.png|border=1!

h6. 1. Browse Products and Buy Product

A customer of the photo community can browse lists of the created community products, i.e. *Product with Photo*. He is also able to add these products to the communities basket. He can also buy the items by using the communities checkout paying with credit card at the partner's community for example. When the customer bought the product an order with one order item will be created at the partner side. Both have a unique id. Order and order item would look as follows for our scenario:

*Order Entity*
|| Field || Value || Description ||
| id | 9 | partner's order id |
| ... | | |
*Order Item Entity*
|| Field || Value || Description ||
| id | 10 | partner's order item id |
| orderId | 9 | partner's order id |
| productId | 1 | partner's product id |
| state | CREATED | partner's order item state |
| ... | | |

h6. 1.1. Submit Order

Having created the order in the photo community database, the partner sends the order to Spreadshirt using Spreadshirt's Order API. The order item contains the data to order the product created by the photographer in the previously described use case, i.e. product 789. The shop id is the id of the partner's shop, i.e. shop 321. The address is the customer's address with the e-mail address of the partner, i.e. ordertracking@photo.community.virtual. This is necessary to avoid that Spreadshirt sends out e-mails to the partner's customers.


*HTTP Request:*

*URL:* POST [http://api.spreadshirt.net/api/v1/orders]
*Payload:*
{code}
<?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="321"/>
<orderItems>
<orderItem>
<shop id="321"/>
<quantity>1</quantity>
<element id="789" type="sprd:product"
xlink:href="http://api.spreadshirt.net/api/v1/shop/321/products/789">
<properties>
<property key="appearance">1</property>
<property key="size">38</property>
</properties>
</element>
<correlation>
<partner>
<orderItemId>10</orderItemId>
</partner>
</correlation>
</orderItem>
</orderItems>
<correlation>
<partner>
<id>123</id>
<orderId>9</orderId>
</partner>
</correlation>
<shipping>
<shippingType id="1"/>
<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>ordertracking@photo.community.virtual</email>
</address>
</shipping>
</order>
{code}

*HTTP Response*:

*Location:*&nbsp;[http://api.spreadshirt.net/api/v1/orders/987]
*Status:* 201 (Created)

h6. Further Reading

* [API:Order Resources]


h5. Partner &nbsp;sends Order Shipping Notification to Customer

!solution_guide_photo_community-use_case-shipping_notification.png|border=1!

h6. 1. Trigger Order State Update

Timer service in community software triggers regular fetching and processing of Spreadshirt's order reports.

h6. 1.1. Fetch OrderReport List

Fetch list of all available order reports for the partner from Spreadshirt.

*HTTP Request:*
*URL:*&nbsp;[http://api.spreadshirt.net/api/v1/orderReports?query=+partnerId\:(123) \+state:(ACTIVATED)|http://api.spreadshirt.net/api/v1/orderReports?query=+partnerId:(123) +state:(ACTIVATED)]
*Payload:*
{code}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orderReports xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
<orderReport id="123" href="http://api.spreadshirt.net/api/v1/orderReports/123">
<state>ACTIVATED</state>
</orderReport>
</orderReports>
{code}
*HTTP Response:*
*Status:* 200 OK

h6. 1.2. Fetch single OrderReport

Fetch single order report in order to be able to process single order item modifications and trigger order state changes in community order tracking software.

*HTTP Request:*
*URL:*&nbsp;[http://api.spreadshirt.net/api/v1/orderReports/123]
*Payload:*
{code}
<?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="987" xlink:href="http://api.spreadshirt.net/api/v1/orders/987"/>
<orderItem id="876"/>
<correlation>
<partner>
<orderItemId id="10"/>
</partner>
</correlation>
<fulfillmentState>RECEIVED</fulfillmentState>
<modified>2011-12-15 08:14:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
<orderItemModification>
<order id="987" xlink:href="http://api.spreadshirt.net/api/v1/orders/987"/>
<orderItem id="876"/>
<correlation>
<partner>    
<orderItemId id="10"/>  
</partner>  
</correlation>
<fulfillmentState>CREATED</fulfillmentState>
<modified>2011-12-15 08:15:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
<orderItemModification>
<order id="987" xlink:href="http://api.spreadshirt.net/api/v1/orders/987"/>
<orderItem id="876"/>
<correlation>  
<partner>  
<orderItemId id="10"/>  
</partner>  
</correlation>  
<fulfillmentState>ACCEPTED</fulfillmentState>
<modified>2011-12-15 08:30:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
<orderItemModification>
<order id="987" xlink:href="http://api.spreadshirt.net/api/v1/orders/987"/>
<orderItem id="876"/>
<correlation>  
<partner>  
<orderItemId id="10"/>  
</partner>  
</correlation>  
<fulfillmentState>IN_PROGRESS</fulfillmentState>
<modified>2011-12-15 12:00:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
<orderItemModification>
<order id="987" xlink:href="http://api.spreadshirt.net/api/v1/orders/987"/>
<orderItem id="876"/>
<correlation>  
<partner>  
<orderItemId id="10"/>  
</partner>  
</correlation>  
<fulfillmentState>SHIPPED</fulfillmentState>
<modified>2011-12-15 17:00:00Z</modified> <!-- we use UTC as timezone -->
</orderItemModification>
</orderItemModifications>
<state>ACTIVATED</state>
<created>2011-12-15 20:00:00</created>
<modified>2011-12-15 20:00:00</modified>
</orderReport>
{code}
*HTTP Response:*
*Status:* 200 OK

h6. 1.3. Update Order State

Update partner's order item state based on order item modifications on Spreadshirt's order items received with the order report. Set order item 10 based on that from state CREATED to SHIPPED.

h6. 1.4. Send Shipping E-Mail

Based on the state change of the order item from CREATED to SHIPPED, the community order tracking service uses the community's email service to send a shipping confirmation e-mail to the customer.

h6. 2. Read Shipping E-Mail

The customer uses his e-mail client to read the shipping confirmation e-mail.

h6. Further Reading

* [API:Order Resources]