Changes for page Sellables

Last modified by Shop Team on 2023/02/13 22:56
From version 1.1 >
edited by jns
on 2019/07/15 12:17
To version < 18.1
edited by Shop Team
on 2023/02/13 22:56
Change comment: Renamed back-links.

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -Public Shop API
1 +Sellables
Parent
... ... @@ -1,0 +1,1 @@
1 +API.Spreadshirt Public Shop API Documentation.API REST Resources.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.jns
1 +XWiki.shop
Content
... ... @@ -1,8 +1,329 @@
1 -(% class="auto-cursor-target" %)
1 += General Remarks =
2 +
3 +These resources only work for shops that are based on the (new) Partner Area, not for legacy User Area-based shops. Terminology:
4 +
5 +* 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**.
6 +* 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.
7 +
8 +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.
9 +
10 +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.
11 +
12 += List Resource =
13 +
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 +)))
29 +
30 +Returns a paginated list of the shop's sellables in a format like this:
31 +
32 +{{code language="js" title="Response Payload"}}
33 +{
34 + "count" : 4760,
35 + "limit" : 48,
36 + "offset" : 0,
37 + "sellables" :
38 + [
39 + {
40 + "sellableId" : "praawgg73zU5gzZN0gaM-812-7",
41 + "ideaId" : "5d22f8ebb264a16f6b87fb6f",
42 + "mainDesignId": "142648902",
43 + "productTypeId" : "812",
44 + "price" :
45 + {
46 + "amount" : 17.49,
47 + "currencyId" : "1"
48 + },
49 + "name" : "I love you",
50 + "tags" :
51 + [
52 + "Young wild and free",
53 + "shop api",
54 + "test",
55 + "Young money",
56 + "Loved",
57 + "Lovestruck",
58 + "Love with heart",
59 + "Love hurts",
60 + "Love",
61 + "Love me",
62 + "Youtube",
63 + "migration",
64 + "Your",
65 + "You",
66 + "Love parade"
67 + ],
68 + "previewImage" :
69 + {
70 + "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",
71 + "type" : "MODEL"
72 + },
73 + "appearanceIds" :
74 + [
75 + "411",
76 + "645",
77 + "648",
78 + "649",
79 + "719",
80 + "1",
81 + "2",
82 + "366",
83 + "348",
84 + "387",
85 + "92",
86 + "39",
87 + "231",
88 + "317",
89 + "3",
90 + "29",
91 + "328",
92 + "339"
93 + ],
94 + "defaultAppearanceId" : "2"
95 + }
96 + ]
97 +}
98 +{{/code}}
99 +
100 +The fields are to be interpreted as follows:
101 +
102 +(% class="wrapped" %)
103 +|=(((
104 +Field
105 +)))|=(((
106 +Description
107 +)))
108 +|(((
109 +sellableId
110 +)))|(((
111 +Unique identifier for the sellable. Necessary to query the detail resource mentioned below as well as for the add-to-basket request.
112 +)))
113 +|(((
114 +ideaId
115 +)))|(((
116 +Identifies the uploaded design. Necessary to query the detail resource but also useful to group content by design if desired.
117 +)))
118 +|(% colspan="1" %)(% colspan="1" %)
119 +(((
120 +(% class="objectBox objectBox-string" %)mainDesignId
121 +)))|(% colspan="1" %)(% colspan="1" %)
122 +(((
123 +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:API.Spreadshirt Public Shop API Documentation.API REST Resources.Design Details.WebHome]] in combination with this resource.
124 +)))
125 +|(((
126 +productTypeId
127 +)))|(((
128 +Identifies the 'type of garment' used. Can be used to lookup additional meta data from the product type resources described [[here>>doc:API.Spreadshirt Public Shop API Documentation.API REST Resources.ProductType.WebHome]].
129 +)))
130 +|(((
131 +price
132 +)))|(((
133 +Always in the currency of the shop. Check [[this>>doc:API.Spreadshirt Public Shop API Documentation.API Tutorials.Build your own shop system.Price Formatting Guide.WebHome]] for hints on how to format the price in a user-friendly way.
134 +)))
135 +|(((
136 +name
137 +)))|(((
138 +The text you entered in the Partner Area.
139 +)))
140 +|(((
141 +description
142 +)))|(((
143 +The text you entered in the Partner Area (optional).
144 +)))
145 +|(((
146 +tags
147 +)))|(((
148 +The text you entered in the Partner Area (optional).
149 +)))
150 +|(((
151 +previewImage
152 +)))|(((
153 +An image we deem best suited to represent the sellable on a list page.
154 +)))
155 +|(((
156 +previewImage/url
157 +)))|(((
158 +The image url you can embed directly into your page.
159 +)))
160 +|(((
161 +previewImage/type
162 +)))|(((
163 +Describes the type of image available from the url using one of the following values: PRODUCT, DESIGN, MODEL, ALTERNATIVE_MODEL.
164 +)))
165 +|(% colspan="1" %)(% colspan="1" %)
166 +(((
167 +appearanceIds
168 +)))|(% colspan="1" %)(% colspan="1" %)
169 +(((
170 +The 'colors' a sellable currently has available for purchase. If you need more information on the colors, the product type resource [[here>>doc:API.Spreadshirt Public Shop API Documentation.API REST Resources.ProductType.WebHome]] is useful.
171 +)))
172 +|(% colspan="1" %)(% colspan="1" %)
173 +(((
174 +defaultAppearanceId
175 +)))|(% colspan="1" %)(% colspan="1" %)
176 +(((
177 +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.
178 +)))
179 +
180 +Please note that this resource returns a maximum of 9504 sellables or 198 full pages. The page parameter must thus always be between 0 and 197 (inclusively).
181 +
182 +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).
183 +This allows you to implement a custom navigation structure, filters, etc. according to your needs.
184 +
185 += Detail Resource =
186 +
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 +)))
202 +
2 2  \\
3 3  
4 -{{info title="Coming soon"}}
5 -<p>As announced at <span class="wikiexternallink"><a shape="rect" href="https://www.spreadshirt.net/forum/t/what-to-do-if-im-still-in-the-legacy-user-area-and-using-spreadshirts-api-or-a-third-party-plugin/6124">https://www.spreadshirt.net/forum/t/what-to-do-if-im-still-in-the-legacy-user-area-and-using-spreadshirts-api-or-a-third-party-plugin/6124</a></span> our new Shop API documentation will be available soon!</p>
6 -{{/info}}
205 +Returns detailed information on a specific sellable in a specific appearance in a format like this:
7 7  
207 +{{code language="js" title="Response Payload"}}
208 +{
209 + "sizeIds" :
210 + [
211 + "2",
212 + "3",
213 + "4",
214 + "5",
215 + "6",
216 + "38",
217 + "94",
218 + "102"
219 + ],
220 + "images" :
221 + [
222 + {
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",
224 + "type" : "MODEL"
225 + },
226 + {
227 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/compositions/T812A2PA3811PT17X50Y96D163261757FS2991/views/1,width=650,height=650,appearanceId=411.jpg",
228 + "type" : "DESIGN"
229 + },
230 + {
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"
233 + },
234 + {
235 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/3,width=650,height=650,appearanceId=411.jpg",
236 + "type" : "PRODUCT"
237 + },
238 + {
239 + "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/4,width=650,height=650,appearanceId=411.jpg",
240 + "type" : "PRODUCT"
241 + },
242 + {
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",
244 + "type" : "ALTERNATIVE_MODEL"
245 + }
246 + ],
247 + "sellableId" : "praawgg73zU5gzZN0gaM-812-7",
248 + "ideaId" : "5d22f8ebb264a16f6b87fb6f",
249 + "mainDesignId": "142648902",
250 + "productTypeId" : "812",
251 + "price" :
252 + {
253 + "amount" : 17.49,
254 + "currencyId" : "1"
255 + },
256 + "name" : "112016603 143175205 I love you",
257 + "tags" :
258 + [
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"
274 + ],
275 + "previewImage" :
276 + {
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",
278 + "type" : "MODEL"
279 + },
280 + "appearanceIds" :
281 + [
282 + "411",
283 + "645",
284 + "648",
285 + "649",
286 + "719",
287 + "1",
288 + "2",
289 + "366",
290 + "348",
291 + "387",
292 + "92",
293 + "39",
294 + "231",
295 + "317",
296 + "3",
297 + "29",
298 + "328",
299 + "339"
300 + ],
301 + "defaultAppearanceId" : "2"
302 +}
303 +{{/code}}
304 +
8 8  \\
306 +
307 +Most of the fields are exactly the same as in the list resource and have the same semantics. Two additional fields are included:
308 +
309 +(% class="wrapped" %)
310 +|=(((
311 +Field
312 +)))|=(((
313 +Meaning
314 +)))
315 +|(((
316 +sizeIds
317 +)))|(((
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:API.Spreadshirt Public Shop API Documentation.API REST Resources.ProductType.WebHome]].
319 +)))
320 +|(((
321 +images
322 +)))|(((
323 +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).
324 +)))
325 +
326 +Implementation remarks: It is not feasible to import these detail resources into your own data base (because the number of entries can skyrocket quickly).
327 +Instead, it is recommended to request the API dynamically in an ad-hoc manner once a customer visits a detail page.
328 +
329 +\\
venn.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.XWikiGuest
Size
... ... @@ -1,0 +1,1 @@
1 +81.8 KB
Content
Confluence.Code.ConfluencePageClass[0]
id
... ... @@ -1,1 +1,1 @@
1 -28278794
1 +28278792
url
... ... @@ -1,1 +1,1 @@
1 -https://developer.spreadshirt.net/wiki/spaces/API/pages/28278794/Public Shop API
1 +https://developer.spreadshirt.net/wiki/spaces/API/pages/28278792/Sellables

Navigation