Carts API¶
These endpoints will allow you to easily manage cart and cart items. Base URI is /api/v1/carts/.
Note
Remember that a Cart in Sylius is an Order in the state cart
.
If you don’t understand the difference between Cart and Order concepts in Sylius yet, please read this article carefully.
Cart API response structure¶
If you request a cart via API, you will receive an object with the following fields:
Field | Description |
---|---|
id | Id of the cart |
items | List of items in the cart |
itemsTotal | Sum of all items prices |
adjustments | List of adjustments related to the cart |
adjustmentsTotal | Sum of all cart adjustments values |
total | Sum of items total and adjustments total |
customer | The customer object serialized with the default data for cart |
channel | The channel object serialized with the default data |
currencyCode | Currency of the cart |
localeCode | Locale of the cart |
checkoutState | State of the checkout process of the cart |
CartItem API response structure¶
Each CartItem in an API response will be build as follows:
Field | Description |
---|---|
id | Id of the cart item |
quantity | Quantity of item units |
unitPrice | Price of each item unit |
total | Sum of units total and adjustments total of that cart item |
units | A collection of units related to the cart item |
unitsTotal | Sum of all units prices of the cart item |
adjustments | List of adjustments related to the cart item |
adjustmentsTotal | Sum of all item adjustments related to that cart item |
variant | The product variant object serialized with the default data |
_link[product] | Relative link to product |
_link[variant] | Relative link to variant |
_link[order] | Relative link to order |
CartItemUnit API response structure¶
Each CartItemUnit API response will be build as follows:
Field | Description |
---|---|
id | Id of the cart item unit |
adjustments | List of adjustments related to the unit |
adjustmentsTotal | Sum of all units adjustments of the unit |
Adjustment API response structure¶
And each Adjustment will be build as follows:
Field | Description |
---|---|
id | Id of the adjustment |
type | Type of the adjustment (E.g. order_promotion or tax) |
label | Label of the adjustment |
amount | Amount of the adjustment (value) |
Note
If it is confusing to you, learn more about Carts (Orders) in the component docs and Adjustments concept.
Creating a Cart¶
To create a new cart you will need to call the /api/v1/carts/
endpoint with the POST
method.
Definition¶
POST /api/v1/carts/
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
customer | request | Email of the related customer |
channel | request | Code of the related channel |
localeCode | request | Code of the locale in which the cart should be created |
Example¶
To create a new cart for the shop@example.com
user in the US_WEB
channel with the en_US
locale use the below method:
Warning
Remember, that it doesn’t replicate the environment of shop usage. It is more like an admin part of cart creation, which will allow you to manage the cart from the admin perspective. ShopAPI is still an experimental concept.
$ curl http://demo.sylius.com/api/v1/carts/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
--data '
{
"customer": "shop@example.com",
"channel": "US_WEB",
"localeCode": "en_US"
}
'
Exemplary Response¶
STATUS: 201 Created
{
"id":21,
"items":[
],
"itemsTotal":0,
"adjustments":[
],
"adjustmentsTotal":0,
"total":0,
"customer":{
"id":1,
"email":"shop@example.com",
"firstName":"John",
"lastName":"Doe",
"user":{
"id":1,
"username":"shop@example.com",
"usernameCanonical":"shop@example.com"
},
"_links":{
"self":{
"href":"\/api\/v1\/customers\/1"
}
}
},
"channel":{
"code":"US_WEB",
"_links":{
"self":{
"href":"\/api\/v1\/channels\/US_WEB"
}
}
},
"currencyCode":"USD",
"localeCode":"en_US",
"checkoutState":"cart"
}
Note
A currency code will be added automatically based on the channel settings. Read more about channels here.
Warning
If you try to create a resource without localeCode, channel or customer, you will receive a 400 Bad Request
error, that will contain validation errors.
Example¶
$ curl http://demo.sylius.com/api/v1/carts/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST
Exemplary Response¶
STATUS: 400 Bad Request
{
"code":400,
"message":"Validation Failed",
"errors":{
"children":{
"customer":{
"errors":[
"This value should not be blank."
]
},
"localeCode":{
"errors":[
"This value should not be blank."
]
},
"channel":{
"errors":[
"This value should not be blank."
]
}
}
}
}
Collection of Carts¶
To retrieve a paginated list of carts you will need to call the /api/v1/carts/
endpoint with the GET
method.
Definition¶
GET /api/v1/carts/
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
page | query | (optional) Number of the page, by default = 1 |
paginate | query | (optional) Number of carts displayed per page, by default = 10 |
Example¶
To see the first page of the paginated carts collection use the below method:
$ curl http://demo.sylius.com/api/v1/carts/ \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
Exemplary Response¶
STATUS: 200 OK
{
"page":1,
"limit":10,
"pages":1,
"total":1,
"_links":{
"self":{
"href":"\/api\/v1\/carts\/?page=1&limit=10"
},
"first":{
"href":"\/api\/v1\/carts\/?page=1&limit=10"
},
"last":{
"href":"\/api\/v1\/carts\/?page=1&limit=10"
}
},
"_embedded":{
"items":[
{
"id":21,
"items":[
],
"itemsTotal":0,
"adjustments":[
],
"adjustmentsTotal":0,
"total":0,
"customer":{
"id":1,
"email":"shop@example.com",
"firstName":"John",
"lastName":"Doe",
"user":{
"id":1,
"username":"shop@example.com",
"enabled":true
},
"_links":{
"self":{
"href":"\/api\/v1\/customers\/1"
}
}
},
"channel":{
"id":1,
"code":"US_WEB",
"_links":{
"self":{
"href":"\/api\/v1\/channels\/US_WEB"
}
}
},
"currencyCode":"USD",
"localeCode":"en_US",
"checkoutState":"cart"
}
]
}
}
Getting a Single Cart¶
To retrieve details of the cart you will need to call the /api/v1/carts/{id}
endpoint with GET
method.
Definition¶
GET /api/v1/carts/{id}
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
id | url attribute | Id of the requested cart |
Example¶
To see details of the cart with id = 21
use the below method:
$ curl http://demo.sylius.com/api/v1/carts/21 \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
Note
The 21 value was taken from the previous create response. Your value can be different. Check in the list of all carts if you are not sure which id should be used.
Exemplary Response¶
STATUS: 200 OK
{
"id":21,
"items":[
],
"itemsTotal":0,
"adjustments":[
],
"adjustmentsTotal":0,
"total":0,
"customer":{
"id":1,
"email":"shop@example.com",
"firstName":"John",
"lastName":"Doe",
"user":{
"id":1,
"username":"shop@example.com",
"usernameCanonical":"shop@example.com"
},
"_links":{
"self":{
"href":"\/api\/v1\/customers\/1"
}
}
},
"channel":{
"code":"US_WEB",
"_links":{
"self":{
"href":"\/api\/v1\/channels\/US_WEB"
}
}
},
"currencyCode":"USD",
"localeCode":"en_US",
"checkoutState":"cart"
}
Deleting a Cart¶
To delete a cart you will need to call the /api/v1/carts/{id}
endpoint with the DELETE
method.
Definition¶
DELETE /api/v1/carts/{id}
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
id | url attribute | Id of the requested cart |
Example¶
To delete the cart with id = 21
use the below method:
$ curl http://demo.sylius.com/api/v1/carts/21 \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json" \
-X DELETE
Note
Remember the 21 value comes from the previous example. Here we are deleting a previously fetched cart, so it is the same id.
Exemplary Response¶
STATUS: 204 No Content
Creating a Cart Item¶
To add a new cart item to an existing cart you will need to call the /api/v1/carts/{cartId}/items/
endpoint with POST
method.
Definition¶
POST /api/v1/carts/{cartId}/items/
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
cartId | url attribute | Id of the requested cart |
variant | request | Code of the item you want to add to the cart |
quantity | request | Amount of variants you want to add to the cart (cannot be < 1) |
Example¶
To add a new item of a variant with code MEDIUM_MUG_CUP
to the cart with id = 21 (assuming, that we didn’t remove it in the previous example) use the below method:
$ curl http://demo.sylius.com/api/v1/carts/21/items/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
--data '
{
"variant": "MEDIUM_MUG_CUP",
"quantity": 1
}
'
Exemplary Response¶
STATUS: 201 Created
{
"id":57,
"quantity":1,
"unitPrice":250,
"total":250,
"units":[
{
"id":165,
"adjustments":[
],
"adjustmentsTotal":0
}
],
"unitsTotal":250,
"adjustments":[
],
"adjustmentsTotal":0,
"variant":{
"id":331,
"code":"MEDIUM_MUG_CUP",
"optionValues":[
{
"code":"mug_type_medium",
"translations":{
"en_US":{
"id":1,
"value":"Medium mug"
}
}
}
],
"position":2,
"translations":{
"en_US":{
"id":331,
"name":"Medium Mug"
}
},
"tracked":false,
"channelPricings":{
"US_WEB": {
"channelCode": "US_WEB",
"price":250
}
}
},
"_links":{
"order":{
"href":"\/api\/v1\/orders\/21"
},
"product":{
"href":"\/api\/v1\/products\/07f2044a-855d-3c56-9274-b5167c2d5809"
},
"variant":{
"href":"\/api\/v1\/products\/07f2044a-855d-3c56-9274-b5167c2d5809\/variants\/MEDIUM_MUG_CUP"
}
}
}
Tip
In Sylius the prices are stored as an integers (1059
represents 10.59$
).
So in order to present a proper amount to the end user, you should divide price by 100 by default.
Updating a Cart Item¶
To change the quantity of a cart item you will need to call the /api/v1/carts/{cartId}/items/{cartItemId}
endpoint with the PUT
or PATCH
method.
Definition¶
PUT /api/v1/carts/{cartId}/items/{cartItemId}
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
cartId | url attribute | Id of the requested cart |
cartItemId | url attribute | Id of the requested cart item |
quantity | request | Amount of items you want to have in the cart (cannot be < 1) |
Example¶
To change the quantity of the cart item with id = 57
in the cart of id = 21
to 3 use the below method:
$ curl http://demo.sylius.com/api/v1/carts/21/items/57 \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X PUT \
--data '{"quantity": 3}'
Tip
If you are not sure where does the value 58 come from, check the previous response, and look for the cart item id.
Exemplary Response¶
STATUS: 204 No Content
Now we can check how does the cart look like after changing the quantity of a cart item.
$ curl http://demo.sylius.com/api/v1/carts/21 \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
Exemplary Response¶
STATUS: 200 OK
{
"id":21,
"items":[
{
"id":57,
"quantity":3,
"unitPrice":250,
"total":750,
"units":[
{
"id":165,
"adjustments":[
],
"adjustmentsTotal":0
},
{
"id":166,
"adjustments":[
],
"adjustmentsTotal":0
},
{
"id":167,
"adjustments":[
],
"adjustmentsTotal":0
}
],
"unitsTotal":750,
"adjustments":[
],
"adjustmentsTotal":0,
"variant":{
"id":331,
"code":"MEDIUM_MUG_CUP",
"optionValues":[
{
"code":"mug_type_medium",
"translations":{
"en_US":{
"id":1,
"value":"Medium mug"
}
}
}
],
"position":2,
"translations":{
"en_US":{
"id":331,
"name":"Medium Mug"
}
},
"tracked":false,
"channelPricings":{
"US_WEB": {
"channelCode": "US_WEB",
"price":250
}
}
},
"_links":{
"order":{
"href":"\/api\/v1\/orders\/21"
},
"product":{
"href":"\/api\/v1\/products\/07f2044a-855d-3c56-9274-b5167c2d5809"
},
"variant":{
"href":"\/api\/v1\/products\/07f2044a-855d-3c56-9274-b5167c2d5809\/variants\/MEDIUM_MUG_CUP"
}
}
}
],
"itemsTotal":750,
"adjustments":[
{
"id":181,
"type":"shipping",
"label":"UPS",
"amount":157
}
],
"adjustmentsTotal":157,
"total":907,
"customer":{
"id":1,
"email":"shop@example.com",
"firstName":"John",
"lastName":"Doe",
"user":{
"id":1,
"username":"shop@example.com",
"usernameCanonical":"shop@example.com"
},
"_links":{
"self":{
"href":"\/api\/v1\/customers\/1"
}
}
},
"channel":{
"code":"US_WEB",
"_links":{
"self":{
"href":"\/api\/v1\/channels\/US_WEB"
}
}
},
"currencyCode":"USD",
"localeCode":"en_US",
"checkoutState":"cart"
}
Tip
In this response you can see that promotion and shipping have been taken into account to calculate the appropriate price.
Deleting a Cart Item¶
To delete a cart item from a cart you will need to call the /api/v1/carts/{cartId}/items/{cartItemId}
endpoint with the DELETE
method.
Definition¶
To delete the cart item with id = 58
from the cart with id = 21
use the below method:
DELETE /api/v1/carts/{cartId}/items/{cartItemId}
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
cartId | url attribute | Id of the requested cart |
cartItemId | url attribute | Id of the requested cart item |
Example¶
$ curl http://demo.sylius.com/api/v1/carts/21/items/58 \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json" \
-X DELETE
Exemplary Response¶
STATUS: 204 No Content