Wiki source code of Sellables

Version 12.1 by Shop Team on 2019/08/06 08:23
Show last authors
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 |=(((
15 Method
16 )))|=(((
17 URL
18 )))|=(((
19 Example
20 )))
21 |(((
22 GET
23 )))|(((
24 {{{/api/v1/shops/<shopId>/sellables?page=<page>}}}
25 )))|(((
26 (% 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"]]
27 )))
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 "productTypeId" : "812",
43 "price" :
44 {
45 "amount" : 17.49,
46 "currencyId" : "1"
47 },
48 "name" : "I love you",
49 "tags" :
50 [
51 "Young wild and free",
52 "shop api",
53 "test",
54 "Young money",
55 "Loved",
56 "Lovestruck",
57 "Love with heart",
58 "Love hurts",
59 "Love",
60 "Love me",
61 "Youtube",
62 "migration",
63 "Your",
64 "You",
65 "Love parade"
66 ],
67 "previewImage" :
68 {
69 "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",
70 "type" : "MODEL"
71 },
72 "appearanceIds" :
73 [
74 "411",
75 "645",
76 "648",
77 "649",
78 "719",
79 "1",
80 "2",
81 "366",
82 "348",
83 "387",
84 "92",
85 "39",
86 "231",
87 "317",
88 "3",
89 "29",
90 "328",
91 "339"
92 ],
93 "defaultAppearanceId" : "2"
94 }
95 ]
96 }
97 {{/code}}
98
99 The fields are to be interpreted as follows:
100
101 (% class="wrapped" %)
102 |=(((
103 Fiel
104 )))|=(((
105 Description
106 )))
107 |(((
108 sellableId
109 )))|(((
110 Unique identifier for the sellable. Necessary to query the detail resource mentioned below as well as for the add-to-basket request.
111 )))
112 |(((
113 ideaId
114 )))|(((
115 Identifies the uploaded design. Necessary to query the detail resource but also useful to group content by design if desired.
116 )))
117 |(((
118 productTypeId
119 )))|(((
120 Identifies the 'type of garment' used. Can be used to lookup additional meta data from the product type resources described [[here>>doc:ProductType]].
121 )))
122 |(((
123 price
124 )))|(((
125 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.
126 )))
127 |(((
128 name
129 )))|(((
130 The text you entered in the Partner Area.
131 )))
132 |(((
133 description
134 )))|(((
135 The text you entered in the Partner Area (optional).
136 )))
137 |(((
138 tags
139 )))|(((
140 The text you entered in the Partner Area (optional).
141 )))
142 |(((
143 previewImage
144 )))|(((
145 An image we deem best suited to represent the sellable on a list page.
146 )))
147 |(((
148 previewImage/url
149 )))|(((
150 The image url you can embed directly into your page.
151 )))
152 |(((
153 previewImage/type
154 )))|(((
155 Describes the type of image available from the url using one of the following values: PRODUCT, DESIGN, MODEL, ALTERNATIVE_MODEL.
156 )))
157 |(% colspan="1" %)(% colspan="1" %)
158 (((
159 appearanceIds
160 )))|(% colspan="1" %)(% colspan="1" %)
161 (((
162 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.
163 )))
164 |(% colspan="1" %)(% colspan="1" %)
165 (((
166 defaultAppearanceId
167 )))|(% colspan="1" %)(% colspan="1" %)
168 (((
169 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.
170 )))
171
172
173 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).
174 This allows you to implement a custom navigation structure, filters, etc. according to your needs.
175
176 = Detail Resource =
177
178 |=(((
179 Method
180 )))|=(((
181 URL
182 )))|=(((
183 Example
184 )))
185 |(((
186 GET
187 )))|(((
188 {{{/api/v1/shops/<shopId>/sellables/<sellableId>?appearanceId=<appearanceId>&ideaId=<ideaId>}}}
189 )))|(((
190 (% 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"]]
191 )))
192
193 \\
194
195 Returns detailed information on a specific sellable in a specific appearance in a format like this:
196
197 {{code language="js" title="Response Payload"}}
198 {
199 "sizeIds" :
200 [
201 "2",
202 "3",
203 "4",
204 "5",
205 "6",
206 "38",
207 "94",
208 "102"
209 ],
210 "images" :
211 [
212 {
213 "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",
214 "type" : "MODEL"
215 },
216 {
217 "url" : "https://image.spreadshirtmedia.net/image-server/v1/compositions/T812A2PA3811PT17X50Y96D163261757FS2991/views/1,width=650,height=650,appearanceId=411.jpg",
218 "type" : "DESIGN"
219 },
220 {
221 "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",
222 "type" : "MODEL"
223 },
224 {
225 "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/3,width=650,height=650,appearanceId=411.jpg",
226 "type" : "PRODUCT"
227 },
228 {
229 "url" : "https://image.spreadshirtmedia.net/image-server/v1/products/T812A2PA3811PT17X50Y96D163261757FS2991/views/4,width=650,height=650,appearanceId=411.jpg",
230 "type" : "PRODUCT"
231 },
232 {
233 "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",
234 "type" : "ALTERNATIVE_MODEL"
235 }
236 ],
237 "sellableId" : "praawgg73zU5gzZN0gaM-812-7",
238 "ideaId" : "5d22f8ebb264a16f6b87fb6f",
239 "productTypeId" : "812",
240 "price" :
241 {
242 "amount" : 17.49,
243 "currencyId" : "1"
244 },
245 "name" : "112016603 143175205 I love you",
246 "tags" :
247 [
248 "Young wild and free",
249 "shop api",
250 "test",
251 "Young money",
252 "Loved",
253 "Lovestruck",
254 "Love with heart",
255 "Love hurts",
256 "Love",
257 "Love me",
258 "Youtube",
259 "migration",
260 "Your",
261 "You",
262 "Love parade"
263 ],
264 "previewImage" :
265 {
266 "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",
267 "type" : "MODEL"
268 },
269 "appearanceIds" :
270 [
271 "411",
272 "645",
273 "648",
274 "649",
275 "719",
276 "1",
277 "2",
278 "366",
279 "348",
280 "387",
281 "92",
282 "39",
283 "231",
284 "317",
285 "3",
286 "29",
287 "328",
288 "339"
289 ],
290 "defaultAppearanceId" : "2"
291 }
292 {{/code}}
293
294 \\
295
296 Most of the fields are exactly the same as in the list resource and have the same semantics. Two additional fields are included:
297
298 (% class="wrapped" %)
299 |=(((
300 Field name
301 )))|=(((
302 Meaning
303 )))
304 |(((
305 sizeIds
306 )))|(((
307 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]].
308 )))
309 |(((
310 images
311 )))|(((
312 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).
313 )))
314
315
316 Implementation remarks: It is not feasible to import these detail resources into your own data base (because the number of entries can skyrocket quickly).
317 Instead, it is recommended to request the API dynamically in an ad-hoc manner once a customer visits a detail page.
318
319 \\

Navigation