Skip to end of metadata
Go to start of metadata

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

Resources

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:

additionally token can be defined

or full basket payload can be given

See Basket Representation

Response Representation:

Header:

Location: .../v1/baskets/70aab75c0b6217c2aff1fe301111929291

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:

<basket ...>
  ...
</basket>

See Basket Representation

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  basket to ...)

APIKey

true

SessionId

false

Request Payload:

<basket ...>
  .....
</basket>

See Basket Representation

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

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:

<basketItem ...>
    ...
</basketItem>

See Basket Item Representation

Response Representation:

Header:

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:

<basketItem ...>
   .....
</basketItem>

See Basket Item Representation

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:

<basketItem ...>
  ...
</basketItem>

See Basket Item Representation

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

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:

<?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"/>

Representations

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.

basket/user

Reference to the user (customer) that owns that basket. Null means the basket belongs to no specific customer.

basket/basketItems

List of basket items that are actually in the basket. See Basket Item for more details.

basket/links

Different links, for example shop checkout link, platform checkout link or default checkout link that is calculated for the current basket.

basket/shipping

Shipping data for basket.

basket/shipping/shippingType

The selected shippingType.

basket/shipping/price

The shipping price.

basket/discounts

List of discounts that apply and total discount value (for all basket items -> basket item discount x basket item quantity).

basket/priceItems

Total for all basket items only without shipping cost, discounts, etc. (for all basket items -> basket price item x basket item quantity).

basket/priceTotal

Total for basket with price of all items, discounts, shipping costs, etc..

Example:

You can find more basket examples in the API browser application .

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 and Retrieve Article ). 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

appearance: 1 (Depends on the product type. Check the productType resource to determine the appearanceId)
size: 2 (Depends on the product type. Check the productType resource to determine the sizeId)
appearanceLabel: i18n name of product type appearance, e.g. Red
sizeLabel: i18n name of product type size, e.g. M
appearanceLink: link to product type appearance color image, e.g. http://image.spreadshirt.net/image-server/v1/appearances/15

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/discounts

The possible discounts and the discount value per single item that applies.

basketItem/priceItem

The single basket item price without reductions through discounts, etc..

basketItem/price

The single basket item price. Price is calculated by the API. Price contains discount reductions.

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:

You can find more basket item examples in the API browser application .

Discount calculation example

  • only basket item where shop and product type of article/product support discounts are considered 
  • quantities of considered basket items are summed up per used discount scale (for mixed baskets we could have items from different shops with different discount scales - in this case quantities are summed up per used discount scale and not in total)
  • with the summed up quantities we check the corresponding discount scale for a matching discount - if we find a discount, we store it
  • we check the basket items again and check whether a discount for the item is granted - in case a discount is granted we calculated the percentage discount on the item
  • to find out the granted discount for a specific discount scale, we sum up the item discounts

Use Cases

Add Article to Basket and Checkout


 

1. + 2. Retrieve Article

Retrieve an existing article.

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

Status Code 200
Payload:

<?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>

3. + 4. Retrieve Basket

Retrieve an existing basket or create new basket.

Request is

POST .../v1/baskets

Payload:

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

Response is

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

5. + 6. POST Basket Item

Request is

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

Payload:

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

Response is

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

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=...

9. + 10. Checkout

Request is

POST https://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:

Checkout HTML Page
  • No labels