Baskets

Last modified by Shop Team on 2023/02/13 22:55

Create a basket

Method

URL

Example

POST

/api/v1/baskets

https://api.spreadshirt.net/api/v1/baskets?mediaType=json

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.

Example Payload
{
  "basketItems" :
      [
         {
           "quantity" : 1,
           "element" :
               {
                 "id" : "praawgg73zU5gzZN0gaM-812-7",
                 "type" : "sprd:sellable",
                 "properties" :
                     [
                        {
                          "key" : "size",
                          "value" : "3"
                        },
                        {
                          "key" : "appearance",
                          "value" : "2"
                        }
                     ],
                 "shop" :
                     {
                       "id" : "100488332"
                     }
               }
         }
      ]
}


Field

Description

basketItems

An array that can contain 0-n entries.

basketItems/quantity

The quantity of the specific basket item that the customer selected.

basketItems/element/id

SellableId of the sellable you want to put into the basket.

basketItems/element/type

A constant for all Partner Area based shops. Always use "sprd:sellable".

basketItems/element/properties

This array of key-value-pairs must always contain values for "size" and "appearance".

basketItems/element/shop/id

The id of your shop.

A successful request is answered with HTTP status code 201 and a response payload looking like this:

Response Payload
{
   "href": "https://api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5",
   "id": "5ad33740-30ad-41b0-846f-9e1f0c6824b5"
}

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.


Retrieve a basket

Method

URL

Example

GET

/api/v1/baskets/<basketId>

https://api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5?mediaType=json


Query Parameter

Description

locale

Use on of the values described here. This will affect the assumed shipping costs as well as the localized names of "description", "sizeLabel" and "appearanceLabel".


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.

Example Response Payload

{
  "href" : "https://api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5",
  "id" : "5ad33740-30ad-41b0-846f-9e1f0c6824b5",
  "shop" :
      {
        "href" : "https://api.spreadshirt.net/api/v1/shops/100488332",
        "id" : "100488332"
      },
  "currency" :
      {
        "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
        "id" : "1"
      },
  "language" :
      {
        "href" : "https://api.spreadshirt.net/api/v1/languages/2",
        "id" : "2"
      },
  "country" :
      {
        "href" : "https://api.spreadshirt.net/api/v1/countries/1",
        "id" : "1"
      },
  "shipping" :
      {
        "price" :
            {
              "vatExcluded" : 4.16,
              "vatIncluded" : 4.99,
              "display" : 4.99,
              "vat" : 20,
              "currency" :
                  {
                    "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
                    "id" : "1"
                  }
            },
        "priceItem" :
            {
              "vatExcluded" : 4.16,
              "vatIncluded" : 4.99,
              "display" : 4.99,
              "vat" : 20,
              "currency" :
                  {
                    "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
                    "id" : "1"
                  }
            }
      },
  "priceItems" :
      {
        "vatExcluded" : 14.58,
        "vatIncluded" : 17.49,
        "display" : 17.49,
        "currency" :
            {
              "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
              "id" : "1"
            }
      },
  "priceTotal" :
      {
        "vatExcluded" : 18.74,
        "vatIncluded" : 22.48,
        "display" : 22.48,
        "currency" :
            {
              "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
              "id" : "1"
            }
      },
  "basketItems" :
      [
         {
           "href" : "https://api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5/items/672b26f1-e9e5-479b-973a-cfba1d1c8139",
           "id" : "672b26f1-e9e5-479b-973a-cfba1d1c8139",
           "description" : "Men’s Premium T-Shirt",
           "quantity" : 1,
           "element" :
               {
                 "id" : "praawgg73zU5gzZN0gaM-812-7",
                 "type" : "sprd:sellable",
                 "shop" :
                     {
                       "href" : "https://api.spreadshirt.net/api/v1/shops/100488332",
                       "id" : "100488332"
                     },
                 "properties" :
                     [
                        {
                          "key" : "size",
                          "value" : "3"
                        },
                        {
                          "key" : "sizeLabel",
                          "value" : "M"
                        },
                        {
                          "key" : "appearance",
                          "value" : "2"
                        },
                        {
                          "key" : "appearanceLabel",
                          "value" : "black"
                        },
                        {
                          "key" : "sellable",
                          "value" : "praawgg73zU5gzZN0gaM-812-7"
                        },
                        {
                          "key" : "idea",
                          "value" : "5d22f8ebb264a16f6b87fb6f"
                        },
                        {
                          "key" : "product",
                          "value" : "524053687"
                        },
                        {
                          "key" : "productType",
                          "value" : "812"
                        },
                        {
                          "key" : "appearanceLink",
                          "value" : "http://image.spreadshirtmedia.net/image-server/v1/appearances/2"
                        }
                     ]
               },
           "shop" :
               {
                 "href" : "https://api.spreadshirt.net/api/v1/shops/100488332",
                 "id" : "100488332"
               },
           "priceItem" :
               {
                 "vatExcluded" : 14.58,
                 "vatIncluded" : 17.49,
                 "display" : 17.49,
                 "vat" : 20,
                 "currency" :
                     {
                       "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
                       "id" : "1"
                     }
               },
           "price" :
               {
                 "vatExcluded" : 14.58,
                 "vatIncluded" : 17.49,
                 "display" : 17.49,
                 "vat" : 20,
                 "currency" :
                     {
                       "href" : "https://api.spreadshirt.net/api/v1/currencies/1",
                       "id" : "1"
                     }
               }
         }
      ],
  "links" :
      [
         {
           "type" : "defaultCheckout",
           "href" : "https://checkout.spreadshirt.de/en?basketId=5ad33740-30ad-41b0-846f-9e1f0c6824b5"
         },
         {
           "type" : "shopCheckout",
           "href" : "https://checkout.spreadshirt.de/en?basketId=5ad33740-30ad-41b0-846f-9e1f0c6824b5&shopId=100488332"
         },
         {
           "type" : "platformCheckout",
           "href" : "https://checkout.spreadshirt.de/en?basketId=5ad33740-30ad-41b0-846f-9e1f0c6824b5"
         }
      ]
}

The most important fields are summarized as follows:

Field

Description

shipping/priceItem/display

Assumed shipping price for standard shipping without shipping discounts. (The exact price depends on the customer's location.)

shipping/price/display

Assumed shipping price for standard shipping with shipping discounts subtracted. (The exact price depends on the customer's location.)

priceItems/display

Total price of all basket items with discounts already subtracted.

priceTotal/display

Total price of all basket items (with discounts already subtracted) plus shipping/price/display. This is what you usually want to dispay as total.

basketItems/description

Human-readable product type description. Depends on the locale parameter.

basketItems/quantity

This is what you sent when creating the basket.

basketItems/element/id

This is what you sent when creating the basket.

basketItems/element/properties

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.

basketItems/priceItem/display

The price for an item with quantity=1 without taking discounts into account.

basketItems/price/display

The price for an item with quantity=1 with discounts subtracted.

links

Use the link with type "shopCheckout" to redirect your customer to Spreadshirt's checkout.


Update a basket

Method

URL

Example

PUT

/api/v1/baskets/<basketId>

https://api.spreadshirt.net/api/v1/baskets/5ad33740-30ad-41b0-846f-9e1f0c6824b5?mediaType=json

Allows to update an existing basket by overwriting its content. This works as follows:

  1. Retrieve an existing basket via GET.
  2. Modify the response payload according to your needs.
  3. Send the modified payload via PUT.
  4. In the response body, the result of the update is returned. Save and display this response; an additional GET request is thus not required.

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

Tags: