The Basket Model (API Terminology Explained #5)

In one of my last blog posts, I told you about our product model and described what the difference between article and product is. I also told you how to retrieve products and articles and gave you a first idea on how to create new products.
In this blog post, I will tell you more about our basket model and how you can use baskets to add articles or products as basket items and forward customers with these baskets to our HTML checkout.

Understanding the Basket Model

In our terminology, a basket contains a set of abstract basket items that link concrete basket item elements. Right now, two concrete basket item elements are supported: Spreadshirt product and article. However, the mechanism is extendable and will later allow to support articles from external partner as well.
A typical basket, e.g. a basket with one article, is illustrated in the picture above. A basket has right now the following characteristics:

  • Core Data: Each basket can have a token, a shop id and a user id. The token can be used in case the client is not able to store the basket id, but still needs to be able to reference a created basket via a unique client-generated id somehow.
    The shop id can be used to create a basket that is connected to a specific shop. The direct effect of that is, that the API returns a checkout URL that points to the shop checkout. Omit the shop id, if you want to use the Spreadshirt platform (marketplace) checkout.
    The user id can be used to connect the basket to a specific user. You can omit the user id by default.
  • Basket Items: A basket can have, depending on its state, zero or more basket items. A basket item represents an abstract item added to the basket. Each basket item has a description, a quantity, a price, a shop id and a concrete basket item element.
    The concrete basket item element has a type attribute, which can right now be set to the supported types sprd:article or sprd:product, and a xlink:href attribute which links the actual product or article that is available via the API. Depending on the type, one can set type specific element properties. In case of Spreadshirt article and product, these properties are size and appearance.
    Please note that price and description are taken from the item linked by the basket item element. Quantity is always a value greater equal 1.
    You can only add products or articles to a basket, if they are available in the desired size and appearance (see product’s product type stock states). Some products do not allow to change the default color (freeColorSelection = false) and thus can not be added to the basket in a different appearance than the configured one.

Right now, we only provide a very simple basket model via the API. However, we will further improve the basket model and will also allow to provide for example a shipping address, coupon codes or additional correlation information. Stay tuned.

Creating  Baskets

According to our REST API’s resource types and their semantic, you can create a basket by conducting a HTTP POST request on http://api.spreadshirt.net/api/v1/baskets with the following XML payload:

<basket xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns="http://api.spreadshirt.net">
   <!--optional in case shop checkout shall be used-->
   <!--shop id="42"/-->
</basket>

As explained before, in case you want to use your Spreadshirt shop checkout, you need to provide your shop id. Omit the shop id, in case you want to use Spreadshirt’s platform checkout.

As response to the HTTP POST request, the API will return a Location header the contains the URL of the created basket. You can now use this URL to retrieve the created basket with a HTTP GET request,  to add basket items with HTTP POST requests or to delete the basket with a HTTP DELETE request.

To add a basket item to the basket, you simply conduct a HTTP POST request with the following XML payload on http://api.spreadshirt.net/api/v1/baskets/123/basketItems, where 123 is the fictitious id of your created basket:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<basketItem xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
    <quantity>1</quantity>
    <element id="5017990" type="sprd:article"
             xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/articles/5017990">
        <properties>
            <property key="appearance">114</property>
            <property key="size">38</property>
        </properties>
    </element>
</basketItem>

Having added the basket item to your basket, the interesting question is: How can you forward your customer from your custom application to the Spreadshirt shop or platform checkout?
This is actually quite simple! The API provides a URL that returns for a given basket the HTML checkout URL. By conducting a HTTP GET request on http://api.spreadshirt.net/api/v1/baskets/123/checkout, you will retrieve a reference similar to the following one:

<?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.net/de/DE/Platform/Controller-2001/
                       Checkout/Basket/cart/basket/7da453af-fb8e-47eb-9cbc-015b78426859"/>

Now, you can use the URL from the xlink:href attribute to conduct a browser redirect and forward your customer to our checkout.

Please note, that you need an API key, to work with API baskets. Please also note, that you can browse and test the API using our API browser. For the full documentation of basket resources provided via the API and our basket XML payload, have a look at the basket resources page on our Spreadshirt developer wiki.

Summary

In this blog post, I gave you an introduction to our basket model. I told you how to create baskets, add basket items and forward customers from your custom application to our Spreadshirt shop or platform checkout. With this knowledge, you can create your first custom application.
In my next blog posts, I will tell you more about how to create new products and how to upload designs via the API.

Please also have a look at the other articles in the series “API Terminology Explained”:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<basketItem xmlns:xlink=”http://www.w3.org/1999/xlink” xmlns=”http://api.spreadshirt.net”>
<quantity>1</quantity>
<element id=”5017990″ type=”sprd:article”
xlink:href=”http://api.spreadshirt.net/api/v1/shops/205909/articles/5017990″>
<properties>
<property key=”appearance”>114</property>
<property key=”size”>98</property>
</properties>
</element>
</basketItem>