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