Skip to end of metadata
Go to start of metadata

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 know 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 

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.

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)

Use Cases relevant for Integration Scenario with Spreadshirt

  1. Photographer creates t-shirt with his photo in his community space
  2. Customer buys a t-shirt in the photo community
  3. Partner sends order shipping notification to customer
Photographer creates T-Shirt with his Photo in his Community Space

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 and create products with Spreadshirt. The application should work similar to Spreadshirt's Confomat 7 or Spreadshirt's Simplomat 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

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

Payload:

HTTP Response:

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

Status: 201 (Created)

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 http://image.spreadshirt.net/api/v1/designs/u456?mediaType=xml

Payload: 

HTTP Response:

Status: 200 (OK)

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

1.3. Create Product

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

HTTP Request:

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

Payload:

HTTP Response:

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

Status: 201 (Created)

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

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: 

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

Spreadshirt product link

Further Reading
Customer buys a T-Shirt at the Photo Community

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

...

 

 

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:

HTTP Response:

Location: http://api.spreadshirt.net/api/v1/orders/987
Status: 201 (Created)

Further Reading
Partner  sends Order Shipping Notification to Customer

1. Trigger Order State Update

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

1.1. Fetch OrderReport List

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

HTTP Request:
URL: http://api.spreadshirt.net/api/v1/orderReports?query=+partnerId\:(123) +state:(ACTIVATED)
Payload:

HTTP Response:
Status: 200 OK

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: http://api.spreadshirt.net/api/v1/orderReports/123
Payload:

HTTP Response:
Status: 200 OK

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.

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.

2. Read Shipping E-Mail

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

Further Reading