Basket Resources

{excerpt}This document specifies the API of the basket service, which allows to create, retrieve, update and delete shopping baskets.{excerpt}

{toc:depth=2|maxLevel=2}





h1. Resources

h2. Create Basket

Creates a new basket in case no basket for the given combination of token and shopId exists or returns an existing basket identified by that combination.


|| Url | .../v1/baskets ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets] ||
|| Type | List ||
|| Method | POST ||
|| Special Status Codes | 201 (return found/created basket) ||
|| APIKey | true ||
|| SessionId | false ||

*Request Representation:*

Minimum representation is:

{code}
<basket/>
{code}

additionally token can be defined

{code}
<basket>
<token>xy</token>
</basket>
{code}

and shop can be added
{code}
<basket>
<token>xy</token>
<shop id="42"/>
</basket>
{code}
See [Basket Representation|#Basket]

















*Response Representation:*

Header:

{noformat}Location: .../v1/baskets/70aab75c0b6217c2aff1fe301111929291{noformat}


h2. Retrieve Basket

Returns an existing basket identified by the given basket id.

|| Url | .../v1/baskets/\{basketId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets/20000001] ||
|| Type | Entity ||
|| Method | GET ||
|| Special Status Codes | ||
|| APIKey | true ||
|| SessionId | false ||

*Response Payload:*

{noformat}
<basket ...>
...
</basket>
{noformat}

See [Basket Representation|#Basket]





















h2. Update Basket

Updates a basket and its basket items.


|| Url | .../v1/baskets/\{basketId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets/20000001] ||
|| Type | Entity ||
|| Method | PUT ||
|| Special Status Codes | 403 (shop&nbsp; basket to ...) \\ ||
|| APIKey | true ||
|| SessionId | false ||

*Request Payload:*

{noformat}
<basket ...>
.....
</basket>
{noformat}

See [Basket Representation|#Basket]





















h2. Delete Basket

Deletes a basket from the platform.


|| Url | .../v1/baskets/\{basketId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets/20000001] ||
|| Type | Entity ||
|| Method | DELETE ||
|| Special Status Codes | ||
|| APIKey | true ||
|| SessionId | false ||

h2. Create Basket Item

Creates a new basket item in the specified basket.


|| Url | .../v1/baskets/\{basketId\}/items ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets/20000001/items] ||
|| Type | List ||
|| Method | POST ||
|| Special Status Codes | 201 (as increment quantity or as created) \\
403 (basket item with element from different shop added to shop specific basket or set quantity to 0) ||
|| APIKey | true ||
|| SessionId | false ||

*Request Representation:*

{noformat}
<basketItem ...>
...
</basketItem>
{noformat}

See [Basket Item Representation|#Basket Item]





















*Response Representation:*

Header:

{code}
Location: .../v1/baskets/20000001/items/456
{code}

h2. Retrieve Basket Item

Returns a basket item of the specified basket.


|| Url | .../v1/baskets/\{basketId\}/items/\{basketItemId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets/20000001/items/456] ||
|| Type | Entity ||
|| Method | GET ||
|| Special Status Codes | ||
|| APIKey | true ||
|| SessionId | false ||

*Response Representation:*

{noformat}
<basketItem ...>
.....
</basketItem>
{noformat}

See [Basket Item Representation|#Basket Item]





















h2. Update Basket Item

Updates the specified basket item.


|| Url | .../v1/baskets/\{basketId\}/items/\{basketItemId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets/20000001/items/456] ||
|| Type | Entity ||
|| Method | PUT ||
|| Special Status Codes | 403 (basket item not allowed in shop specific basket/ wrong quantity) ||
|| APIKey | true ||
|| SessionId | false ||

*Request Representation:*

{noformat}
<basketItem ...>
...
</basketItem>
{noformat}

See [Basket Item Representation|#Basket Item]





















h2. Delete Basket Item

Deletes the specified basket item from the basket.


|| Url | .../v1/baskets/\{basketId\}/items/\{basketItemId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets/20000001/items/456] ||
|| Type | Entity ||
|| Method | DELETE ||
|| Special Status Codes | ||
|| APIKey | true ||
|| SessionId | false ||



h2. Retrieve Basket Checkout URL

Returns the checkout URL for your basket that you can use to send your customer's browser to our Spreadshirt marketplace or shop checkout. In case you created you basket for a specific shop, the returned URL will point to the shop checkout. In case you created your basket for no specific shop, the returned URL will point to our marketplace checkout.

|| Url | .../v1/baskets/\{basketId\}/checkout ||
|| Sample | [http://api.spreadshirt.net/api/v1/baskets/20000001/checkout] ||
|| Type | Entity ||
|| Method | GET ||
|| Special Status Codes | ||
|| APIKey | true ||
|| SessionId | false ||

*Response Payload:*

{noformat}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reference xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net" xlink:href="https://www.spreadshirt.com/us-us/-C2001/Checkout/Basket/cart/basket/58b0c256-81ce-4d26-a709-0e2962d9a4a7"/>
{noformat}

h1. Representations

h2. Basket

|| Field || Description ||
| basket \\ | Representation of a platform basket. \\ |
| basket/token \\ | A 40 character token that can be created by a client programm and passed to the platform on basket retrieval. Can be used to later retrieve the same basket in case the basket id is not known. Token could be a session id for example. \\ |
| basket/shop \\ | Reference to the shop for which you created that basket. Null means the basket belongs to no shop, i.e. to the Spreadshirt marketplace right now. \\ |

{code}
<basket id="0cd283f7-5b24-407a-9a9c-a081455e1030"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://api.spreadshirt.net"
xlink:href="http://api.spreadshirt.net/api/v1/baskets/0cd283f7-5b24-407a-9a9c-a081455e1030">
<token>xy</token>
<user id="42" xlink:href="http://api.spreadshirt.net/v1/users/42"/>
<shop id="42" xlink:href="http://api.spreadshirt.net/v1/shops/42"/>
<basketItems>
<basketItem ...>
... see below
</basketItem>

You can find more basket examples in the [API browser application|API Browser] .


h2. BasketItem

|| Field || Description ||
| basketItem \\ | Representation of a basket item on the platform. \\ |
| basketItem/description \\ | A text that describes the basket item. Usually the article or product text. Will be generated automatically on basket item creation. \\ |
| basketItem/quantity \\ | The number of items the customer wants to buy. Is always an int > 0. In case you want to delete a basket item use HTTP DELETE method\! This attribute is mandatory for basket item creations. \\ |
| basketItem/element \\ | The abstract element that you want to place into the basket. \\ |
| basketItem/element/@id | The id of the abstract thing the customer bought. Allowed right now are Spreadshirt article id and product ids. Will be set automatically on basket item creation. \\ |
| basketItem/element/@xlink:href | A link to the actual concrete element you placed into the basket. Can be either a link to a Spreadshirt article or product right now (see [Retrieve Product|API:Product Resources#Retrieve Shop Product Entity] and [Retrieve Article|API:Product Resources#Retrieve Shop Article Entity] ). This attribute is mandatory for basket item creations. \\ |
| basketItem/element/@type | The actual type of the abstract element which makes it to a concrete one. Can be _sprd:article_ or _sprd:product_ for Spreadshirt articles or products right now. Type is mandatory for basket item creations. \\ |
| basketItem/element/properties | A list of properties that further refine the abstract element. \\ |
| basketItem/element/properties/property \\ | A property value that corresponds to the property key, e.g. size:2 or appearance:1. Properties might be different depending on the element type. Spreadshirt articles and products support size and appearance only. Properties are mandatory for basket item creations. \\ |
| basketItem/element/properties/property/@key | |
| basketItem/links \\ | list of links that belong to actions that can be executed for this basket item \\ |
| basketItem/links/link \\ | concrete link of link list \\ |
| basketItem/links/link@type \\ | link type that can be either edit or continueShopping. edit link is the link displayed in checkout for editing the basket item. continueShopping link is used in checkout as link for continue shopping button. \\ |
| basketItem/links/link@xlink:href \\ | actual URL \\ |
| basketItem/price \\ | The single basket item price. Price is calculated by the API. \\ |
| basketItem/shop \\ | In case of mixed mode basket, a reference to the shop where the customer bought the item. \\ |
| basketItem/origin | Reference to the origin of the basket. Origin can be used to tell the platform, where the basket item actually comes from, i.e. from which product or sales channel. |


Example:
{code}
<basketItem
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://api.spreadshirt.net"
xlink:href="http://api.spreadshirt.net/api/v1/baskets/0cd283f7-5b24-407a-9a9c-a081455e1030/items/a561dcbb-9065-4e45-ad20-aba2bd8a6afa"
id="a561dcbb-9065-4e45-ad20-aba2bd8a6afa">
<!-- optional for mixed mode -->
<shop id="40000" xlink:href="http://api.spreadshirt.net/v1/shops/42">
<description>Basket Item description</description>
<quantity>2</quantity>
<element id="456" type="sprd:article" xlink:href="http://api.spreadshirt.net/v1/shops/42/articles/456">
<properties>
<property key="appearance">15</property>
<property key="size">12</property>
</properties>
</element>
<links>
<link type="edit" xlink:href="http://www.yourdomain.de/article/123/edit"/>
<link type="continueShopping" xlink:href="http://www.yourdomain.de"/>
</links>
 <price>
<currency id="1" xlink:href="http://api.spreadshirt.net/v1/currencies/1"/>
<vatIncluded>10.0</vatIncluded>
<vatExcluded>9.8</vatExcluded>
<vat>0.2</vat>
</price>
</basketItem>
{code}

You can find more basket item examples in the [API browser application|API Browser] .


h1. Use Cases

h2. Add Article to Basket and Checkout


!Basket Usage.png!
&nbsp;

h3. 1. + 2. Retrieve Article

Retrieve an existing article.

GET .../v1/shops/40000/articles/2876817

Status Code 200
*Payload:*
{noformat}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<article xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net" weight="4.0" id="2876817">
...
</article>
{noformat}

h3. 3. + 4. Retrieve Basket

Retrieve an existing basket or create new basket.

Request is

POST .../v1/baskets

Payload:
{noformat}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<basket xmlns="http://api.spreadshirt.net">
<shop id="40000"/>
</basket>
{noformat}
Response is

*Status Code:* 200 (OK) or 201 (Created) - depends on the case
*Header:*
Location: .../baskets/70aab75c0b6217c2aff1fe301111929291

h3. 5. + 6. POST Basket Item

Request is

POST .../v1/baskets/70aab75c0b6217c2aff1fe301111929291/items

*Payload:*
{noformat}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<basketItem xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
...
</basketItem>
{noformat}
Response is

*Status Code:* 201 (Created)
*Header:*
Location: .../baskets/70aab75c0b6217c2aff1fe301111929291/items/123

h3. 7. + 8. Retrieve Basket Checkout URL

Request is

GET ...v1/baskets/70aab75c0b6217c2aff1fe301111929291/checkout

Response is

*Status Code:* 200 (OK)
*Header:*
Location: [https://www.spreadshirt.net/.../checkout?basketId=70aab75c0b6217c2aff1fe301111929291&sig=|http://www.spreadshirt.net/.../checkout?basketId=70aab75c0b6217c2aff1fe301111929291&sig=]...

h3. 9. + 10. Checkout

Request is

POST [https://www.spreadshirt.net/.../checkout?basketId=70aab75c0b6217c2aff1fe301111929291&sig=|http://www.spreadshirt.net/.../checkout?basketId=70aab75c0b6217c2aff1fe301111929291&sig=]...

*Header:*
Cookie: spreadshirt cookie with spreadshirt PHP session id \|\| sessionId as parameter

Response is

*Status Code:* 200 (OK)
*Payload:*
{noformat}Checkout HTML Page
{noformat}