Preface
Spreadshirt provides several ways to offer an online shop experience to your customers:
- The standalone Spreadshop (this, for example). This application is officially developed, hosted and maintained by Spreadshirt. Running a Spreadshop requires zero technical skills and is always the recommended approach.
- JavaScript integration (described here). If you have an existing website, you can embed a piece of JavaScript into it that manipulates your website in order to embed the Spreadshop into your site. This requires a decent understanding of HTML and CSS in order to resolve any conflicts between your site and the Spreadshop that may arise.
- CMS plugins for WordPress and others (currently just Joomla) that embed the JavaScript snippet mentioned in (2.) for you. If you run a website based on such CMS, these plugins can make your life a bit easier. An understanding of HTML and CSS is nonetheless important.
- An independent, custom built web application based on the Public Shop API described in this document. This interface is for web developers only (or people who can afford to hire one). Going for this approach is only feasible for people who have a solid understanding of server side & client side programming, HTTP, HTML and CSS.
Prerequisites
The Public Shop API only works for shops that are based on the (new) Partner Area, not for legacy User Area-based shops. On top of that, an API key is required.
Note that not only the content you upload in the Partner Area, but also the shop settings affect the output of the Public Shop API. For example, enabling model images affects the image URLs returned by the API.
Terminology
Partner Area shops are not based on the old domain entities articles and products anymore. Instead, they are based on ideas and sellables (sic!).
- an idea represents an image you uploaded in the Partner Area that you gave a name and added other meta data to. In the Partner Area this is loosely referred to as a design.
- a sellable is a representation of an idea printed on a product type. Depending on the product range selected in the Partner Area, one idea might have 100+ sellables associated with it.
A sellable is thus something concrete that a customer can buy, while an idea represents a grouping of content mainly intended to make administration easier.
Changelog
- 22 July 2019: 1.0
- The field previewImage as well as the content of the images array have been changed from strings to objects. These objects now contain information about the image type.
- Introduced a legacy article mapping resource.
- 27 June 2019: Beta
- Beta release with request for feedback
REST Resources
Base URLs
As always, use https://api.spreadshirt.com if your shop is based on the North American Spreadshirt platform or use https://api.spreadshirt.net if your shop runs on the European platform.
Authentication
Please provide your API key as described here. A signature or sessionId is not required.
Remember to set a user agent header naming your application and including its version. Example: "MyApp-1.0"
Client / Server
All requests to the Public Shop API should be made from your server and not from the browser. This allows you to leverage caching, avoids CORS policy interference and keeps your API key secure.
List Resource
Returns a paginated list of the shop's sellables in a format like this:
"count" : 473,
"limit" : 48,
"offset" : 0,
"sellables" :
[
{
"sellableId" : "74bYwmw5a3tXgyZpnw7j-812-7",
"ideaId" : "5c7e78f95fd3e45786249fb0",
"productTypeId" : "812",
"price" :
{
"amount" : 21.99,
"currencyId" : "1"
},
"name" : "Boss in black",
"description" : "Be your own boss in black and printed by real people in black!",
"tags" :
[
"Fanwear",
"SpreadShop",
"Awesome"
],
"previewImage" :
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/1,width=500,height=500,appearanceId=1,crop=list,modelId=85,version=1554885779/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "MODEL"
},
"appearanceIds" :
[
"411",
"645",
"649",
"1",
"366",
"92",
"39",
"231",
"317",
"3",
"29",
"328"
],
"defaultAppearanceId" : "1"
},
// more sellables
]
}
The fields are to be interpreted as follows:
Field name | Meaning |
|---|---|
sellableId | Unique identifier for the sellable. Necessary to query the detail resource mentioned below as well as for the add-to-basket request. |
ideaId | Identifies the uploaded design. Necessary to query the detail resource but also useful to group content by design if desired. |
productTypeId | Identifies the 'type of garment' used. Can be used to lookup additional meta data from the product type resources described here. |
price | Always in the currency of the shop. Check this for hints on how to format the price in a user-friendly way. |
name | The text you entered in the Partner Area. |
description | The text you entered in the Partner Area (optional). |
tags | The text you entered in the Partner Area (optional). |
previewImage | An image we deem best suited to represent the sellable on a list page. |
previewImage.url | The image url you can embed directly into your page. |
previewImage.type | Describes the type of image available from the url using one of the following values: PRODUCT, DESIGN, MODEL, ALTERNATIVE_MODEL. |
appearanceIds | The 'colors' a sellable currently has available for purchase. If you need more information on the colors, the product type resource here is useful. |
defaultAppearanceId | The default 'color' you can set in the Partner Area. This is the color the previewImage is in. It also provides a good starting point when linking to a detail page. |
Implementation remarks: For advanced implementations, it is usually best to import the content of the sellable list into your own data base in regular intervals (for example once every 24h).
This allows you to implement a custom navigation structure, filters, etc. according to your needs.
Detail Resource
Returns detailed information on a specific sellable in a specific appearance in a format like this:
"sizeIds" :
[
"2",
"3",
"4",
"5",
"6",
"38",
"94",
"102"
],
"images" :
[
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/1,width=650,height=650,appearanceId=411,crop=detail,modelId=85,version=1554885779/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "MODEL"
},
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/2,width=650,height=650,appearanceId=411,crop=detail,modelId=91,version=1554885805/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "MODEL"
},
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/compositions/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/1,width=650,height=650,appearanceId=411/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "DESIGN"
},
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/compositions/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/2,width=650,height=650,appearanceId=411/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "DESIGN"
},
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/3,width=650,height=650,appearanceId=411/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "PRODUCT"
},
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/4,width=650,height=650,appearanceId=411/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "PRODUCT"
},
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/1,width=650,height=650,appearanceId=411,crop=detail,modelId=1111,version=1554884899/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "ALTERNATIVE_MODEL"
}
],
"sellableId" : "74bYwmw5a3tXgyZpnw7j-812-7",
"ideaId" : "5c7e78f95fd3e45786249fb0",
"productTypeId" : "812",
"price" :
{
"amount" : 21.99,
"currencyId" : "1"
},
"name" : "Boss in black",
"description" : "Be your own boss in black and printed by real people in black!",
"tags" :
[
"Fanwear",
"SpreadShop",
"Awesome"
],
"previewImage" :
{
"url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A1PA3811PT17X49Y84D142648902FS2951PA3813PT17X60Y17D142648934FS2706/views/1,width=500,height=500,appearanceId=1,crop=list,modelId=85,version=1554885779/be-your-own-boss-in-black-and-printed-by-real-people-in-black.jpg",
"type" : "MODEL"
},
"appearanceIds" :
[
"411",
"645",
"649",
"1",
"366",
"92",
"39",
"231",
"317",
"3",
"29",
"328"
],
"defaultAppearanceId" : "1"
}
Most of the fields are exactly the same as in the list resource and have the same semantics. Two additional fields are included:
Field name | Meaning |
|---|---|
sizeIds | Describes the sizes available for purchase for the sellable in this appearance. For more information on sizes, check the product type resource here. |
images | A number of images giving an adequate overview over the sellable and it's properties in this appearance when displayed (ordered from most important to least important image). The exact number and shape of the images depend on your shop settings and the specifications you set when uploading the design. This object has the same structure as previewImage (mentioned in the list resource section). |
Implementation remarks: It is not feasible to import these detail resources into your own data base (because the number of entries can skyrocket quickly).
Instead, it is recommended to request the API dynamically in an ad-hoc manner once a customer visits a detail page.
Basket resources
The basket resources generally still work as they used to. However, keep in mind that a sellable is a new domain entity and hence different from products and articles.
To put a sellable into a basket, use this payload fragment instead:
<properties>
<property key="appearance">539</property>
<property key="size">3</property>
</properties>
<shop id="100229382" href="https://api.spreadshirt.net/api/v1/shops/100229382"/>
</element>
Note that the type property needs a different constant now and a shop tag needs to be sent as well.
Legacy article mapping resource
If your shop was subject to a migration from the old model (that was based on articles and was accessible through the User Area), you may still have deeplinks or internal data structures referencing these now-gone articles.
To ease the transition phase, we provide the following resource that allows you to find the corresponding sellable your article was migrated to:
The response contains the identifiers necessary to make the connection between old and new domain entities.
"ideaId": "5d0a19935fd3e41d7dd6900f",
"productTypeId": "725",
"sellableId": "R43XoE5rBATzxQnRNykG-725-9"
}
Frequently Asked Questions
This is too abstract for me. Do you have code examples available?
Yes, there is an example integration of this API available here.
It shows a draft of a shop system written in php that might be helpful to understand the (list-page -> detail-page -> add-to-basket) workflow.
My account is still User Area based. How do I test my integration before I get migrated?
If you do not own a Partner Area based shop yet, but need something "in hand" to develop your implementation, you can rely on the example shop 100488332 provided by us. The shop is available on the European platform (.net) only. You can use articleId=999999999 to test the legacy article mapping resource in this shop.
Which parts of Spreadshirt's API are still valid and what exactly changed?
The good news is that the vast majority of the domain entities and their corresponding REST resources were not changed. They are still valid and work like they used to. However, articles and articleCategories became obsolete and will stop working once you are migrated. Products still exist, but they should not be worked with directly anymore when developing an online shop integration. Use ideas and sellables instead. as described in this document.
I am using a non-official designer-tool integration. How can I enable editing of sellables for my customers?
The designer tool can be bootstrapped with a parameter named sellableId. This will only work in Sketchomat/Smartomat, but not in Tablomat. Alternatively, bootstrapping the tool with productType & design still works.