Cart API
Overview
The Cart API provides endpoints for managing shopping carts in your EverShop store. These endpoints allow you to create carts, add or remove items, set customer information, specify shipping and billing addresses, and select shipping and payment methods.
Endpoints
Create a New Cart
Creates a new shopping cart in the system. You can optionally include customer information and initial cart items.
Field Name | Field Type | Required | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
customer_full_name | string | No | |||||||||
customer_email | string | No | |||||||||
items | array of object | Yes | |||||||||
|
- cURL
- JavaScript
curl
-H "Accept: application/json"
https://<your domain>/api/carts
fetch('https://<your domain>/api/carts', {
headers: {
'Accept': 'application/json',
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"data": {
"items": {
"cart_item_id": "2sl0ifz1etgldt28vm9",
"uuid": "4a6e5c9e0062489e82a472aeda0211be",
"product_id": 2,
"product_sku": "NJC90842-Blue-S",
"group_id": 1,
"product_name": "Lite racer adapt 3.0 shoes",
"thumbnail": "/assets/catalog/7385/1316/plv1138-Blue-thumb.png",
"product_weight": 5.4,
"product_price": 823,
"product_price_incl_tax": 823,
"qty": 10,
"final_price": 823,
"tax_percent": 0,
"tax_amount": 0,
"final_price_incl_tax": 823,
"variant_group_id": 62,
"variant_options": "[{"attribute_code":"size","attribute_name":"Size","attribute_id":2,"option_id":25,"option_text":"S"},{"attribute_code":"color","attribute_name":"Color","attribute_id":3,"option_id":8,"option_text":"Blue"}]",
"product_custom_options": null,
"productUrl": "/product/lite-racer-adapt-3.0-shoes",
"removeUrl": "/api/cart/mine/items/4a6e5c9e0062489e82a472aeda0211be",
"discount_amount": 0,
"total": 8230
},
"count": 3,
"cartId": "251ca17e754f4473a9bdf97c85509a4a"
}
}
Add Item to Cart
Adds a product to an existing cart. Specify the product SKU and quantity to add.
Field Name | Field Type | Required |
---|---|---|
sku | string | Yes |
qty | string or integer | Yes |
- cURL
- JavaScript
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items
fetch('https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items', {
headers: {
'Accept': 'application/json',
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"data": {
"item": [
{
"cart_item_id": "2sl0ifz1etgldt28vm9",
"uuid": "4a6e5c9e0062489e82a472aeda0211be",
"product_id": 2,
"product_sku": "NJC90842-Blue-S",
"group_id": 1,
"product_name": "Lite racer adapt 3.0 shoes",
"thumbnail": "/assets/catalog/7385/1316/plv1138-Blue-thumb.png",
"product_weight": 5.4,
"product_price": 823,
"product_price_incl_tax": 823,
"qty": 10,
"final_price": 823,
"tax_percent": 0,
"tax_amount": 0,
"final_price_incl_tax": 823,
"variant_group_id": 62,
"variant_options": "[{"attribute_code":"size","attribute_name":"Size","attribute_id":2,"option_id":25,"option_text":"S"},{"attribute_code":"color","attribute_name":"Color","attribute_id":3,"option_id":8,"option_text":"Blue"}]",
"product_custom_options": null,
"productUrl": "/product/lite-racer-adapt-3.0-shoes",
"removeUrl": "/api/cart/mine/items/4a6e5c9e0062489e82a472aeda0211be",
"discount_amount": 0,
"total": 8230
}
],
"count": 3,
"cartId": "251ca17e754f4473a9bdf97c85509a4a"
}
}
Remove Item from Cart
Removes a specific item from the cart. Requires the cart ID and the item ID to be removed.
- cURL
- JavaScript
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items/433ba97f-8be7-4be9-be3f-a9f341f2b89f
fetch('https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items/433ba97f-8be7-4be9-be3f-a9f341f2b89f', {
headers: {
'Accept': 'application/json',
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"data": {
"item": {
"cart_item_id": 1138,
"uuid": "433ba97f-8be7-4be9-be3f-a9f341f2b89f",
"product_id": 1,
"product_sku": "NJC90842-Blue-X",
"group_id": 1,
"product_name": "Lite racer adapt 3.0 shoes",
"thumbnail": "/assets/catalog/1817/5605/plv1138-Blue-thumb.png",
"product_weight": 5.4,
"product_price": 823,
"product_price_incl_tax": 823,
"qty": 10,
"final_price": 823,
"tax_percent": 0,
"tax_amount": 0,
"final_price_incl_tax": 823,
"variant_group_id": 62,
"variant_options": "[{"attribute_code":"size","attribute_name":"Size","attribute_id":2,"option_id":4,"option_text":"X"},{"attribute_code":"color","attribute_name":"Color","attribute_id":3,"option_id":8,"option_text":"Blue"}]",
"product_custom_options": null,
"productUrl": "/product/lite-racer-adapt-3.0-shoes",
"removeUrl": "/api/cart/mine/items/19fa0c23bbd24edeaa3885940cf59f80",
"discount_amount": 0,
"total": 8230
}
}
}
Add Customer Information
Associates a customer email with the cart. This is a required step in the checkout process before adding addresses.
Field Name | Field Type | Required |
---|---|---|
string | Yes |
- cURL
- JavaScript
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/contacts
fetch('https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/contacts', {
headers: {
'Accept': 'application/json',
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"data": {
"email": "customer@example.com"
}
}
Add Address
Adds a shipping or billing address to the cart. Both address types are required to complete the checkout process.
Field Name | Field Type | Required | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
address | object | Yes | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
type | string (shipping, billing) | Yes |
- cURL
- JavaScript
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/addresses
fetch('https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/addresses', {
headers: {
'Accept': 'application/json',
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"data": {
"cart_address_id": 461,
"uuid": "9c79451aa63211edb46b60d819134f39",
"full_name": "John Doe",
"postcode": "5000",
"telephone": "123456",
"country": "US",
"province": "CA",
"city": "California",
"address_1": "1234 Main St",
"address_2": null
}
}
Add Shipping Method
Specifies the shipping method to be used for the order. This step is required after adding a shipping address and before placing the order.
Field Name | Field Type | Required |
---|---|---|
method_code | string | Yes |
method_name | string | Yes |
- cURL
- JavaScript
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingMethods
fetch('https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingMethods', {
headers: {
'Accept': 'application/json',
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"data": {
"method": {
"code": "free_shipping",
"name": "Free Shipping"
}
}
}
Add Payment Method
Specifies the payment method to be used for the order. This is the final step required before placing the order.
Field Name | Field Type | Required |
---|---|---|
method_code | string | Yes |
method_name | string | Yes |
- cURL
- JavaScript
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/paymentMethods
fetch('https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/paymentMethods', {
headers: {
'Accept': 'application/json',
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"data": {
"method": {
"code": "paypal",
"name": "Paypal"
}
}
}
Get Cart
Retrieves detailed information about a specific cart including items, addresses, and selected shipping and payment methods.
- cURL
- JavaScript
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f
fetch('https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f', {
headers: {
'Accept': 'application/json',
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"data": {
"cart_id": "251ca17e754f4473a9bdf97c85509a4a",
"uuid": "251ca17e754f4473a9bdf97c85509a4a",
"currency": "USD",
"customer_email": "customer@example.com",
"customer_full_name": "John Doe",
"user_ip": "192.168.1.1",
"status": 1,
"total_qty": 3,
"total_weight": 16.2,
"shipping_fee_excl_tax": 0,
"shipping_fee_incl_tax": 0,
"discount_amount": 0,
"sub_total": 8230,
"tax_amount": 0,
"grand_total": 8230,
"shipping_address_id": 460,
"billing_address_id": 461,
"shipping_method": "free_shipping",
"shipping_method_name": "Free Shipping",
"payment_method": "paypal",
"payment_method_name": "PayPal",
"items": [
{
"cart_item_id": "2sl0ifz1etgldt28vm9",
"uuid": "4a6e5c9e0062489e82a472aeda0211be",
"product_id": 2,
"product_sku": "NJC90842-Blue-S",
"product_name": "Lite racer adapt 3.0 shoes",
"thumbnail": "/assets/catalog/7385/1316/plv1138-Blue-thumb.png",
"qty": 10,
"final_price": 823,
"final_price_incl_tax": 823,
"tax_percent": 0,
"tax_amount": 0,
"discount_amount": 0,
"total": 8230
}
],
"shipping_address": {
"cart_address_id": 460,
"uuid": "9c79451aa63211edb46b60d819134f39",
"full_name": "John Doe",
"postcode": "5000",
"telephone": "123456",
"country": "US",
"province": "CA",
"city": "California",
"address_1": "1234 Main St",
"address_2": null
},
"billing_address": {
"cart_address_id": 461,
"uuid": "9c79451aa63211edb46b60d819134f39",
"full_name": "John Doe",
"postcode": "5000",
"telephone": "123456",
"country": "US",
"province": "CA",
"city": "California",
"address_1": "1234 Main St",
"address_2": null
}
}
}
Error Handling
All endpoints may return the following error responses:
Status Code | Description |
---|---|
400 | Bad Request - Invalid parameters |
401 | Unauthorized - Authentication required |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Cart or item not found |
500 | Server Error - Something went wrong |
Error responses follow this format:
{
"error": {
"status": 404,
"message": "Cart not found"
}
}
Checkout Process Flow
The typical checkout process follows these steps:
- Create a Cart - Initialize a new cart for the customer
- Add Items - Add products to the cart
- Add Customer Information - Provide customer email
- Add Addresses - Provide shipping and billing addresses
- Add Shipping Method - Select a shipping method
- Add Payment Method - Select a payment method
- Place Order - Convert the cart to an order (see Order API)
Best Practices
- Error Handling - Always handle API errors gracefully in your frontend application
- Validation - Validate customer inputs before submitting to the API
- Security - Use HTTPS for all API calls to ensure data security