Public Shop API

= Preface =

Spreadshirt provides several ways to offer an online shop experience to your customers:

1. The standalone Spreadshop ([[this>>url:https://shop.spreadshirt.com/SpreadShop||shape="rect"]], 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.

6

1. JavaScript integration (described [[here>>url:https://help.spreadshirt.com/hc/en-us/articles/207487815-Website-Integration-with-JavaScript||shape="rect"]]). 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.

7

1. CMS plugins for [[WordPress>>url:https://wordpress.org/plugins/spreadshop/#developers||shape="rect"]] and others (currently just [[Joomla>>url:https://extensions.joomla.org/extension/spreadshop/||shape="rect"]]) 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.

8

1. 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.

13

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!).

18

19

* 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**.

20

* 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.

21

22

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.

28

** Introduced a **legacy article mapping resource**.

29

* 27 June 2019: Beta

30

** Beta release with request for feedback

= REST Resources =

== Base URLs ==

As always, use [[https:~~/~~/api.spreadshirt.com>>url:https://api.spreadshirt.com||shape="rect"]] if your shop is based on the North American Spreadshirt platform or use [[https:~~/~~/api.spreadshirt.net>>url:https://api.spreadshirt.net||shape="rect"]] if your shop runs on the European platform.

== Authentication ==

Please provide your API key as described [[here>>doc:Security]]. A signature or sessionId is not required.

41

Remember to set a user agent header naming your application and including its version. Example: "MyApp-1.0"

42

43

== Client / Server ==

44

45

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

\\

GET {baseUrl}/api/v1/shops/{shopId}/sellables?page=0

\\

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",

69

"ideaId" : "5c7e78f95fd3e45786249fb0",

70

"productTypeId" : "812",

"price" :

{

"amount" : 21.99,

"currencyId" : "1"

},

"name" : "Boss in black",

77

"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>>doc:Inventory Resources]].

)))

|(((

price

)))|(((

Always in the currency of the shop. Check [[this>>doc:Price Formatting Guide]] for hints on how to format the price in a user-friendly way.

137

)))