Baskets

Version 3.1 by Shop Team on 2019/08/01 12:05

Create a basket

Method

URL

Example

POST

/api/v1/baskets

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.


Read a basket

Method

URL

Example

GET

/api/v1/baskets/<basketId>

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.

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

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.


Tags:
Created by Shop Team on 2019/08/01 11:03