Skip to main content

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.

Request Schema (application/json)
Field NameField TypeRequired
customer_full_namestringNo
customer_emailstringNo
itemsarray of objectYes
Field NameField TypeRequired
skustringYes
qtyintegerYes
POST/api/carts
curl
-H "Accept: application/json"
https://<your domain>/api/carts
Sample Of Response
{
"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.

Request Schema (application/json)
Field NameField TypeRequired
skustringYes
qtystring or integerYes
POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items
Sample Of Response
{
"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.

Request Schema (application/json)
No request body required
DELETE/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items/433ba97f-8be7-4be9-be3f-a9f341f2b89f
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items/433ba97f-8be7-4be9-be3f-a9f341f2b89f
Sample Of Response
{
"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.

Request Schema (application/json)
Field NameField TypeRequired
emailstringYes
POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/contacts
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/contacts
Sample Of Response
{
"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.

Request Schema (application/json)
Field NameField TypeRequired
addressobjectYes
Field NameField TypeRequired
full_namestringYes
telephonestring or numberYes
address_1stringYes
address_2stringNo
citystringYes
provincestringYes
countrystringYes
postcodestringYes
typestring (shipping, billing)Yes
POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/addresses
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/addresses
Sample Of Response
{
"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.

Request Schema (application/json)
Field NameField TypeRequired
method_codestringYes
method_namestringYes
POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingMethods
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingMethods
Sample Of Response
{
"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.

Request Schema (application/json)
Field NameField TypeRequired
method_codestringYes
method_namestringYes
POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/paymentMethods
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/paymentMethods
Sample Of Response
{
"data": {
"method": {
"code": "paypal",
"name": "Paypal"
}
}
}

Get Cart

Retrieves detailed information about a specific cart including items, addresses, and selected shipping and payment methods.

Request Schema (application/json)
No request body required
GET/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f
curl
-H "Accept: application/json"
https://<your domain>/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f
Sample Of Response
{
"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 CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Authentication required
403Forbidden - Insufficient permissions
404Not Found - Cart or item not found
500Server 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:

  1. Create a Cart - Initialize a new cart for the customer
  2. Add Items - Add products to the cart
  3. Add Customer Information - Provide customer email
  4. Add Addresses - Provide shipping and billing addresses
  5. Add Shipping Method - Select a shipping method
  6. Add Payment Method - Select a payment method
  7. Place Order - Convert the cart to an order (see Order API)

Best Practices

  1. Error Handling - Always handle API errors gracefully in your frontend application
  2. Validation - Validate customer inputs before submitting to the API
  3. Security - Use HTTPS for all API calls to ensure data security