Wiki source code of Baskets

Last modified by Shop Team on 2023/02/13 22:55
Show last authors
1 (% class="auto-cursor-target" %)
2 = Create a basket =
3
4 |=(((
5 Method
6 )))|=(((
7 URL
8 )))|=(((
9 Example
10 )))
11 |(((
12 POST
13 )))|(((
14 /api/v1/baskets
15 )))|(((
16 https:~/~/api.spreadshirt.net/api/v1/baskets?mediaType=json
17 )))
18
19 Send a payload as shown below in the request body to create a new basket with any number of basket items in it. A request like this should usually be performed once a new customer interacts with the add-to-basket button for the first time while on your site.
20
21 {{code language="js" title="Example Payload"}}
22 {
23 "basketItems" :
24 [
25 {
26 "quantity" : 1,
27 "element" :
28 {
29 "id" : "praawgg73zU5gzZN0gaM-812-7",
30 "type" : "sprd:sellable",
31 "properties" :
32 [
33 {
34 "key" : "size",
35 "value" : "3"
36 },
37 {
38 "key" : "appearance",
39 "value" : "2"
40 }
41 ],
42 "shop" :
43 {
44 "id" : "100488332"
45 }
46 }
47 }
48 ]
49 }
50 {{/code}}
51
52 \\
53
54 |=(((
55 Field
56 )))|=(((
57 Description
58 )))
59 |(((
60 basketItems
61 )))|(((
62 An array that can contain 0-n entries.
63 )))
64 |(((
65 basketItems/quantity
66 )))|(((
67 The quantity of the specific basket item that the customer selected.
68 )))
69 |(% colspan="1" %)(% colspan="1" %)
70 (((
71 basketItems/element/id
72 )))|(% colspan="1" %)(% colspan="1" %)
73 (((
74 SellableId of the sellable you want to put into the basket.
75 )))
76 |(((
77 basketItems/element/type
78 )))|(((
79 A constant for all Partner Area based shops. Always use "sprd:sellable".
80 )))
81 |(((
82 basketItems/element/properties
83 )))|(((
84 This array of key-value-pairs must always contain values for "size" and "appearance".
85 )))
86 |(% colspan="1" %)(% colspan="1" %)
87 (((
88 basketItems/element/shop/id
89 )))|(% colspan="1" %)(% colspan="1" %)
90 (((
91 The id of your shop.
92 )))
93
94 A successful request is answered with HTTP status code 201 and a response payload looking like this:
95
96 {{code language="js" title="Response Payload"}}
97 {
98 "href": "https://api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5",
99 "id": "5ad33740-30ad-41b0-846f-9e1f0c6824b5"
100 }
101 {{/code}}
102
103 The value of the "id" field should then be remembered in the customer's session because it allows to read or update the same basket as described next.
104
105 (% class="auto-cursor-target" %)
106 \\
107
108 (% class="auto-cursor-target" %)
109 = Retrieve a basket =
110
111 |=(((
112 Method
113 )))|=(((
114 URL
115 )))|=(((
116 Example
117 )))
118 |(((
119 GET
120 )))|(((
121 /api/v1/baskets/<basketId>
122 )))|(((
123 https:~/~/api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5?mediaType=json
124 )))
125
126 (% class="auto-cursor-target" %)
127 \\
128
129 |=(((
130 Query Parameter
131 )))|=(((
132 Description
133 )))
134 |(((
135 locale
136 )))|(((
137 Use on of the values described [[here>>doc:API.Spreadshirt Public Shop API Documentation.API REST Resources.WebHome]]. This will affect the assumed shipping costs as well as the localized names of "description", "sizeLabel" and "appearanceLabel".
138 )))
139
140 \\
141
142 (% class="auto-cursor-target" %)
143 Given an id obtained from creating a basket, this resource allows to read the basket data and it contains additional information that can be useful to show to the customer.
144
145 {{code language="js" title="Example Response Payload"}}
146
147 {
148 "href" : "https://api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5",
149 "id" : "5ad33740-30ad-41b0-846f-9e1f0c6824b5",
150 "shop" :
151 {
152 "href" : "https://api.spreadshirt.net/api/v1/shops/100488332",
153 "id" : "100488332"
154 },
155 "currency" :
156 {
157 "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
158 "id" : "1"
159 },
160 "language" :
161 {
162 "href" : "https://api.spreadshirt.net/api/v1/languages/2",
163 "id" : "2"
164 },
165 "country" :
166 {
167 "href" : "https://api.spreadshirt.net/api/v1/countries/1",
168 "id" : "1"
169 },
170 "shipping" :
171 {
172 "price" :
173 {
174 "vatExcluded" : 4.16,
175 "vatIncluded" : 4.99,
176 "display" : 4.99,
177 "vat" : 20,
178 "currency" :
179 {
180 "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
181 "id" : "1"
182 }
183 },
184 "priceItem" :
185 {
186 "vatExcluded" : 4.16,
187 "vatIncluded" : 4.99,
188 "display" : 4.99,
189 "vat" : 20,
190 "currency" :
191 {
192 "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
193 "id" : "1"
194 }
195 }
196 },
197 "priceItems" :
198 {
199 "vatExcluded" : 14.58,
200 "vatIncluded" : 17.49,
201 "display" : 17.49,
202 "currency" :
203 {
204 "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
205 "id" : "1"
206 }
207 },
208 "priceTotal" :
209 {
210 "vatExcluded" : 18.74,
211 "vatIncluded" : 22.48,
212 "display" : 22.48,
213 "currency" :
214 {
215 "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
216 "id" : "1"
217 }
218 },
219 "basketItems" :
220 [
221 {
222 "href" : "https://api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5/items/672b26f1-e9e5-479b-973a-cfba1d1c8139",
223 "id" : "672b26f1-e9e5-479b-973a-cfba1d1c8139",
224 "description" : "Men’s Premium T-Shirt",
225 "quantity" : 1,
226 "element" :
227 {
228 "id" : "praawgg73zU5gzZN0gaM-812-7",
229 "type" : "sprd:sellable",
230 "shop" :
231 {
232 "href" : "https://api.spreadshirt.net/api/v1/shops/100488332",
233 "id" : "100488332"
234 },
235 "properties" :
236 [
237 {
238 "key" : "size",
239 "value" : "3"
240 },
241 {
242 "key" : "sizeLabel",
243 "value" : "M"
244 },
245 {
246 "key" : "appearance",
247 "value" : "2"
248 },
249 {
250 "key" : "appearanceLabel",
251 "value" : "black"
252 },
253 {
254 "key" : "sellable",
255 "value" : "praawgg73zU5gzZN0gaM-812-7"
256 },
257 {
258 "key" : "idea",
259 "value" : "5d22f8ebb264a16f6b87fb6f"
260 },
261 {
262 "key" : "product",
263 "value" : "524053687"
264 },
265 {
266 "key" : "productType",
267 "value" : "812"
268 },
269 {
270 "key" : "appearanceLink",
271 "value" : "http://image.spreadshirtmedia.net/image-server/v1/appearances/2"
272 }
273 ]
274 },
275 "shop" :
276 {
277 "href" : "https://api.spreadshirt.net/api/v1/shops/100488332",
278 "id" : "100488332"
279 },
280 "priceItem" :
281 {
282 "vatExcluded" : 14.58,
283 "vatIncluded" : 17.49,
284 "display" : 17.49,
285 "vat" : 20,
286 "currency" :
287 {
288 "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
289 "id" : "1"
290 }
291 },
292 "price" :
293 {
294 "vatExcluded" : 14.58,
295 "vatIncluded" : 17.49,
296 "display" : 17.49,
297 "vat" : 20,
298 "currency" :
299 {
300 "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
301 "id" : "1"
302 }
303 }
304 }
305 ],
306 "links" :
307 [
308 {
309 "type" : "defaultCheckout",
310 "href" : "https://checkout.spreadshirt.de/en?basketId=5ad33740-30ad-41b0-846f-9e1f0c6824b5"
311 },
312 {
313 "type" : "shopCheckout",
314 "href" : "https://checkout.spreadshirt.de/en?basketId=5ad33740-30ad-41b0-846f-9e1f0c6824b5&shopId=100488332"
315 },
316 {
317 "type" : "platformCheckout",
318 "href" : "https://checkout.spreadshirt.de/en?basketId=5ad33740-30ad-41b0-846f-9e1f0c6824b5"
319 }
320 ]
321 }
322 {{/code}}
323
324 The most important fields are summarized as follows:
325
326 |=(((
327 Field
328 )))|=(((
329 Description
330 )))
331 |(((
332 shipping/priceItem/display
333 )))|(((
334 Assumed shipping price for standard shipping without shipping discounts. (The exact price depends on the customer's location.)
335 )))
336 |(((
337 shipping/price/display
338 )))|(((
339 Assumed shipping price for standard shipping with shipping discounts subtracted. (The exact price depends on the customer's location.)
340 )))
341 |(((
342 priceItems/display
343 )))|(((
344 Total price of all basket items with discounts already subtracted.
345 )))
346 |(((
347 priceTotal/display
348 )))|(((
349 Total price of all basket items (with discounts already subtracted) plus shipping/price/display. This is what you usually want to dispay as **total**.
350 )))
351 |(((
352 basketItems/description
353 )))|(((
354 Human-readable product type description. Depends on the locale parameter.
355 )))
356 |(((
357 basketItems/quantity
358 )))|(((
359 This is what you sent when creating the basket.
360 )))
361 |(((
362 basketItems/element/id
363 )))|(((
364 This is what you sent when creating the basket.
365 )))
366 |(((
367 basketItems/element/properties
368 )))|(((
369 Aside from the properties that you sent yourself when creating the basket, this also includes the useful human-readable fields "sizeLabel" and "appearanceLabel". These depend on the locale parameter.
370 )))
371 |(% colspan="1" %)(% colspan="1" %)
372 (((
373 basketItems/priceItem/display
374 )))|(% colspan="1" %)(% colspan="1" %)
375 (((
376 The price for an item with quantity=1 without taking discounts into account.
377 )))
378 |(% colspan="1" %)(% colspan="1" %)
379 (((
380 basketItems/price/display
381 )))|(% colspan="1" %)(% colspan="1" %)
382 (((
383 The price for an item with quantity=1 with discounts subtracted.
384 )))
385 |(% colspan="1" %)(% colspan="1" %)
386 (((
387 links
388 )))|(% colspan="1" %)(% colspan="1" %)
389 (((
390 Use the link with type "shopCheckout" to redirect your customer to Spreadshirt's checkout.
391 )))
392
393 (% class="auto-cursor-target" %)
394 \\
395
396 (% class="auto-cursor-target" %)
397 = Update a basket =
398
399 |=(((
400 Method
401 )))|=(((
402 URL
403 )))|=(((
404 Example
405 )))
406 |(((
407 PUT
408 )))|(((
409 /api/v1/baskets/<basketId>
410 )))|(((
411 https:~/~/api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5?mediaType=json
412 )))
413
414 (% class="auto-cursor-target" %)
415 Allows to update an existing basket by overwriting its content. This works as follows:
416
417 1. Retrieve an existing basket via GET.
418 1. Modify the response payload according to your needs.
419 1. Send the modified payload via PUT.
420 1. In the response body, the result of the update is returned. Save and display this response; an additional GET request is thus not required.
421
422 "Modifying the payload" might mean increasing or decreasing a basket item's quantity, adding or removing basket items from the "basketItems" array. Fields like prices can of course not be set by you. It is irrelevant whether you send them with the PUT request or not. However, you need to know how prices change when you increased an item's quantity - that is what the response body is for.

Navigation