Baskets
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.
"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:
"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.
{
"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:
- Retrieve an existing basket via GET.
- Modify the response payload according to your needs.
- Send the modified payload via PUT.
- 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.