Page tree
Skip to end of metadata
Go to start of metadata

Create a basket

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"
                     }
               }
         }
      ]
}


FieldDescription
basketItemsAn array that can contain 0-n entries.
basketItems/quantityThe quantity of the specific basket item that the customer selected.
basketItems/element/idSellableId of the sellable you want to put into the basket.
basketItems/element/typeA constant for all Partner Area based shops. Always use "sprd:sellable".
basketItems/element/propertiesThis array of key-value-pairs must always contain values for "size" and "appearance".
basketItems/element/shop/idThe 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

Query ParameterDescription
localeUse 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:

FieldDescription
shipping/priceItem/displayAssumed shipping price for standard shipping without shipping discounts. (The exact price depends on the customer's location.)
shipping/price/displayAssumed shipping price for standard shipping with shipping discounts subtracted. (The exact price depends on the customer's location.)
priceItems/displayTotal price of all basket items with discounts already subtracted.
priceTotal/displayTotal price of all basket items (with discounts already subtracted) plus shipping/price/display. This is what you usually want to dispay as total.
basketItems/descriptionHuman-readable product type description. Depends on the locale parameter.
basketItems/quantityThis is what you sent when creating the basket.
basketItems/element/idThis is what you sent when creating the basket.
basketItems/element/propertiesAside 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/displayThe price for an item with quantity=1 without taking discounts into account.
basketItems/price/displayThe price for an item with quantity=1 with discounts subtracted.
linksUse the link with type "shopCheckout" to redirect your customer to Spreadshirt's checkout.

Update a basket

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.

  • No labels