Changes for page Sellables

Last modified by Shop Team on 2023/02/13 22:56
<
From version < 8.1 >
edited by Shop Team
on 2019/07/22 08:40
To version < 13.1 >
edited by Shop Team
on 2019/08/30 07:33
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -Public Shop API
1 +Sellables
Content
... ... @@ -1,89 +1,74 @@
1 -= Preface =
1 += General Remarks =
2 2  
3 -Spreadshirt provides several ways to offer an online shop experience to your customers:
3 +These resources only work for shops that are based on the (new) Partner Area, not for legacy User Area-based shops. Terminology:
4 4  
5 -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.
9 -
10 -= Prerequisites =
11 -
12 -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.
14 -
15 -= Terminology =
16 -
17 -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 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 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 21  
22 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.
23 23  
24 -= Changelog =
25 -
26 -* 22 July 2019: 1.0
27 -** 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
31 -
32 -= REST Resources =
33 -
34 -== Base URLs ==
35 -
36 -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.
37 -
38 -== Authentication ==
39 -
40 -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 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>>url:https://en.wikipedia.org/wiki/Cross-origin_resource_sharing||shape="rect"]] policy interference and keeps your API key secure.
46 46  
47 -== List Resource ==
12 += List Resource =
48 48  
49 -\\
14 +(% class="wrapped" %)
15 +|=(((
16 +Method
17 +)))|=(((
18 +URL
19 +)))|=(((
20 +Example
21 +)))
22 +|(((
23 +GET
24 +)))|(((
25 +{{{/api/v1/shops/&#x3c;shopId&#x3e;/sellables?page=&#x3c;page&#x3e;}}}
26 +)))|(((
27 +(% style="color: rgb(80,80,80);" %)[[https:~~/~~/api.spreadshirt.net/api/v1/shops/100488332/sellables?page=0>>url:https://api.spreadshirt.net/api/v1/shops/100488332/sellables?page=0||shape="rect"]]
28 +)))
50 50  
51 -{{code title="Request"}}
52 -GET {baseUrl}/api/v1/shops/{shopId}/sellables?page=0
53 53  
54 -{{/code}}
55 -
56 -\\
57 -
58 58  Returns a paginated list of the shop's sellables in a format like this:
59 59  
60 60  {{code language="js" title="Response Payload"}}
61 61  {
62 - "count" : 473,
35 + "count" : 4760,
63 63   "limit" : 48,
64 64   "offset" : 0,
65 65   "sellables" :
66 66   [
67 67   {
68 - "sellableId" : "74bYwmw5a3tXgyZpnw7j-812-7",
69 - "ideaId" : "5c7e78f95fd3e45786249fb0",
41 + "sellableId" : "praawgg73zU5gzZN0gaM-812-7",
42 + "ideaId" : "5d22f8ebb264a16f6b87fb6f",
43 + "mainDesignId": "142648902",
70 70   "productTypeId" : "812",
71 71   "price" :
72 72   {
73 - "amount" : 21.99,
47 + "amount" : 17.49,
74 74   "currencyId" : "1"
75 75   },
76 - "name" : "Boss in black",
77 - "description" : "Be your own boss in black and printed by real people in black!",
50 + "name" : "I love you",
78 78   "tags" :
79 79   [
80 - "Fanwear",
81 - "SpreadShop",
82 - "Awesome"
53 + "Young wild and free",
54 + "shop api",
55 + "test",
56 + "Young money",
57 + "Loved",
58 + "Lovestruck",
59 + "Love with heart",
60 + "Love hurts",
61 + "Love",
62 + "Love me",
63 + "Youtube",
64 + "migration",
65 + "Your",
66 + "You",
67 + "Love parade"
83 83   ],
84 84   "previewImage" :
85 85   {
86 - "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",
71 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/1,width=500,height=500,appearanceId=2,crop=list,modelId=1111,version=1564481428.jpg",
87 87   "type" : "MODEL"
88 88   },
89 89   "appearanceIds" :
... ... @@ -90,9 +90,14 @@
90 90   [
91 91   "411",
92 92   "645",
78 + "648",
93 93   "649",
80 + "719",
94 94   "1",
82 + "2",
95 95   "366",
84 + "348",
85 + "387",
96 96   "92",
97 97   "39",
98 98   "231",
... ... @@ -99,11 +99,11 @@
99 99   "317",
100 100   "3",
101 101   "29",
102 - "328"
92 + "328",
93 + "339"
103 103   ],
104 - "defaultAppearanceId" : "1"
105 - },
106 - // more sellables
95 + "defaultAppearanceId" : "2"
96 + }
107 107   ]
108 108  }
109 109  {{/code}}
... ... @@ -110,10 +110,11 @@
110 110  
111 111  The fields are to be interpreted as follows:
112 112  
103 +(% class="wrapped" %)
113 113  |=(((
114 -Field name
105 +Fiel
115 115  )))|=(((
116 -Meaning
107 +Description
117 117  )))
118 118  |(((
119 119  sellableId
... ... @@ -125,10 +125,17 @@
125 125  )))|(((
126 126  Identifies the uploaded design. Necessary to query the detail resource but also useful to group content by design if desired.
127 127  )))
119 +|(% colspan="1" %)(% colspan="1" %)
120 +(((
121 +(% class="objectBox objectBox-string" %)mainDesignId
122 +)))|(% colspan="1" %)(% colspan="1" %)
123 +(((
124 +Identifies the main image/design which is used for this Idea (usually the first design you add in the Partner Area). Can be used if you want to use  the [[Designs Resource>>doc:Designs]] in combination with this resource.
125 +)))
128 128  |(((
129 129  productTypeId
130 130  )))|(((
131 -Identifies the 'type of garment' used. Can be used to lookup additional meta data from the product type resources described [[here>>doc:Inventory Resources]].
129 +Identifies the 'type of garment' used. Can be used to lookup additional meta data from the product type resources described [[here>>doc:ProductType]].
132 132  )))
133 133  |(((
134 134  price
... ... @@ -156,12 +156,12 @@
156 156  An image we deem best suited to represent the sellable on a list page.
157 157  )))
158 158  |(((
159 -previewImage.url
157 +previewImage/url
160 160  )))|(((
161 161  The image url you can embed directly into your page.
162 162  )))
163 163  |(((
164 -previewImage.type
162 +previewImage/type
165 165  )))|(((
166 166  Describes the type of image available from the url using one of the following values: PRODUCT, DESIGN, MODEL, ALTERNATIVE_MODEL.
167 167  )))
... ... @@ -170,7 +170,7 @@
170 170  appearanceIds
171 171  )))|(% colspan="1" %)(% colspan="1" %)
172 172  (((
173 -The 'colors' a sellable currently has available for purchase. If you need more information on the colors, the product type resource [[here>>doc:Inventory Resources]] is useful.
171 +The 'colors' a sellable currently has available for purchase. If you need more information on the colors, the product type resource [[here>>doc:ProductType]] is useful.
174 174  )))
175 175  |(% colspan="1" %)(% colspan="1" %)
176 176  (((
... ... @@ -184,12 +184,25 @@
184 184  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).
185 185  This allows you to implement a custom navigation structure, filters, etc. according to your needs.
186 186  
187 -== Detail Resource ==
185 += Detail Resource =
188 188  
189 -{{code title="Request"}}
190 -GET {baseUrl}/api/v1/shops/{shopId}/sellables/{sellableId}?appearanceId={appearanceId}&ideaId={ideaId}
187 +(% class="wrapped" %)
188 +|=(((
189 +Method
190 +)))|=(((
191 +URL
192 +)))|=(((
193 +Example
194 +)))
195 +|(((
196 +GET
197 +)))|(((
198 +{{{/api/v1/shops/&#x3c;shopId&#x3e;/sellables/&#x3c;sellableId&#x3e;?appearanceId=&#x3c;appearanceId&#x3e;&#x26;ideaId=&#x3c;ideaId&#x3e;}}}
199 +)))|(((
200 +(% style="color: rgb(80,80,80);" %)[[https:~~/~~/api.spreadshirt.net/api/v1/shops/100488332/sellables/praawgg73zU5gzZN0gaM-812-7?appearanceId=411&ideaId=5d22f8ebb264a16f6b87fb6f>>url:https://api.spreadshirt.net/api/v1/shops/100488332/sellables/praawgg73zU5gzZN0gaM-812-7?appearanceId=411&ideaId=5d22f8ebb264a16f6b87fb6f||shape="rect"]]
201 +)))
191 191  
192 -{{/code}}
203 +\\
193 193  
194 194  Returns detailed information on a specific sellable in a specific appearance in a format like this:
195 195  
... ... @@ -209,53 +209,61 @@
209 209   "images" :
210 210   [
211 211   {
212 - "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",
223 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/1,width=650,height=650,appearanceId=411,crop=detail,modelId=1111,version=1564481428.jpg",
213 213   "type" : "MODEL"
214 214   },
215 215   {
216 - "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",
217 - "type" : "MODEL"
218 - },
219 - {
220 - "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",
227 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/compositions/T812A2PA3811PT17X50Y96D163261757FS2991/views/1,width=650,height=650,appearanceId=411.jpg",
221 221   "type" : "DESIGN"
222 222   },
223 223   {
224 - "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",
225 - "type" : "DESIGN"
231 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/2,width=650,height=650,appearanceId=411,crop=detail,modelId=1117,version=1564481457.jpg",
232 + "type" : "MODEL"
226 226   },
227 227   {
228 - "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",
235 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/3,width=650,height=650,appearanceId=411.jpg",
229 229   "type" : "PRODUCT"
230 230   },
231 231   {
232 - "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",
239 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/4,width=650,height=650,appearanceId=411.jpg",
233 233   "type" : "PRODUCT"
234 234   },
235 235   {
236 - "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",
243 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/1,width=650,height=650,appearanceId=411,crop=detail,modelId=85,version=1564482744.jpg",
237 237   "type" : "ALTERNATIVE_MODEL"
238 238   }
239 239   ],
240 - "sellableId" : "74bYwmw5a3tXgyZpnw7j-812-7",
241 - "ideaId" : "5c7e78f95fd3e45786249fb0",
247 + "sellableId" : "praawgg73zU5gzZN0gaM-812-7",
248 + "ideaId" : "5d22f8ebb264a16f6b87fb6f",
249 + "mainDesignId": "142648902",
242 242   "productTypeId" : "812",
243 243   "price" :
244 244   {
245 - "amount" : 21.99,
253 + "amount" : 17.49,
246 246   "currencyId" : "1"
247 247   },
248 - "name" : "Boss in black",
249 - "description" : "Be your own boss in black and printed by real people in black!",
256 + "name" : "112016603 143175205 I love you",
250 250   "tags" :
251 251   [
252 - "Fanwear",
253 - "SpreadShop",
254 - "Awesome"
259 + "Young wild and free",
260 + "shop api",
261 + "test",
262 + "Young money",
263 + "Loved",
264 + "Lovestruck",
265 + "Love with heart",
266 + "Love hurts",
267 + "Love",
268 + "Love me",
269 + "Youtube",
270 + "migration",
271 + "Your",
272 + "You",
273 + "Love parade"
255 255   ],
256 256   "previewImage" :
257 257   {
258 - "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",
277 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/1,width=500,height=500,appearanceId=2,crop=list,modelId=1111,version=1564481428.jpg",
259 259   "type" : "MODEL"
260 260   },
261 261   "appearanceIds" :
... ... @@ -262,9 +262,14 @@
262 262   [
263 263   "411",
264 264   "645",
284 + "648",
265 265   "649",
286 + "719",
266 266   "1",
288 + "2",
267 267   "366",
290 + "348",
291 + "387",
268 268   "92",
269 269   "39",
270 270   "231",
... ... @@ -271,9 +271,10 @@
271 271   "317",
272 272   "3",
273 273   "29",
274 - "328"
298 + "328",
299 + "339"
275 275   ],
276 - "defaultAppearanceId" : "1"
301 + "defaultAppearanceId" : "2"
277 277  }
278 278  {{/code}}
279 279  
... ... @@ -281,6 +281,7 @@
281 281  
282 282  Most of the fields are exactly the same as in the list resource and have the same semantics. Two additional fields are included:
283 283  
309 +(% class="wrapped" %)
284 284  |=(((
285 285  Field name
286 286  )))|=(((
... ... @@ -289,7 +289,7 @@
289 289  |(((
290 290  sizeIds
291 291  )))|(((
292 -Describes the sizes available for purchase for the sellable in this appearance. For more information on sizes, check the product type resource [[here>>doc:Inventory Resources]].
318 +Describes the sizes available for purchase for the sellable in this appearance. For more information on sizes, check the product type resource [[here>>doc:ProductType]].
293 293  )))
294 294  |(((
295 295  images
... ... @@ -301,64 +301,4 @@
301 301  Implementation remarks: It is not feasible to import these detail resources into your own data base (because the number of entries can skyrocket quickly).
302 302  Instead, it is recommended to request the API dynamically in an ad-hoc manner once a customer visits a detail page.
303 303  
304 -== Basket resources ==
305 -
306 -The [[basket resources>>doc: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.
307 -To put a sellable into a basket, use this payload fragment instead:
308 -
309 -{{code language="xml" title="Payload Fragment"}}
310 -<element id="MLorqlGGrLhljORQ7old-1007-22" type="sprd:sellable">
311 - <properties>
312 - <property key="appearance">539</property>
313 - <property key="size">3</property>
314 - </properties>
315 - <shop id="100229382" href="https://api.spreadshirt.net/api/v1/shops/100229382"/>
316 -</element>
317 -{{/code}}
318 -
319 -
320 -Note that the **type** property needs a different constant now and a **shop** tag needs to be sent as well.
321 -
322 -== Legacy article mapping resource ==
323 -
324 -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.
325 -To ease the transition phase, we provide the following resource that allows you to find the corresponding sellable your article was migrated to:
326 -
327 -{{code title="Request"}}
328 -GET {baseUrl}/api/v1/shops/{shopId}/sellables/findForArticle?articleId={articleId}
329 -
330 -{{/code}}
331 -
332 -
333 -The response contains the identifiers necessary to make the connection between old and new domain entities.
334 -
335 -{{code language="js" title="Response Payload"}}
336 -{
337 - "ideaId": "5d0a19935fd3e41d7dd6900f",
338 - "productTypeId": "725",
339 - "sellableId": "R43XoE5rBATzxQnRNykG-725-9"
340 -}
341 -{{/code}}
342 -
343 -= Frequently Asked Questions =
344 -
345 -== This is too abstract for me. Do you have code examples available? ==
346 -
347 -Yes, there is an **example integration** of this API available [[here>>url:https://github.com/spreadshirt/shop-api-example-integration||shape="rect"]].
348 -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.
349 -
350 -== My account is still User Area based. How do I test my integration before I get migrated? ==
351 -
352 -(% style="color: rgb(23,43,77);font-size: 14.0px;letter-spacing: 0.0px;" %)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=(% style="font-size: 14.0px;letter-spacing: 0.0px;color: rgb(80,80,80);" %)999999999 to test the **legacy article mapping resource **in this shop.
353 -
354 -== Which parts of Spreadshirt's API are still valid and what exactly changed? ==
355 -
356 -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.
357 -
358 -== [[image:attach:venn.png]]I am using a non-official designer-tool integration. How can I enable editing of sellables for my customers? ==
359 -
360 -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.
361 -
362 362  \\
363 -
364 -\\
Confluence.Code.ConfluencePageClass[0]
id
... ... @@ -1,1 +1,1 @@
1 -28278808
1 +28278939
url
... ... @@ -1,1 +1,1 @@
1 -https://developer.spreadshirt.net/wiki/spaces/API/pages/28278808/Public Shop API
1 +https://developer.spreadshirt.net/wiki/spaces/API/pages/28278939/Sellables

Navigation