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 Name

Field Type

Required

customer_full_name

string

customer_email

string

items

array of object

Yes

Field Name	Field Type	Required
sku	string	Yes
qty	integer	Yes

POST/api/carts

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
  });

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 Name	Field Type	Required
sku	string	Yes
qty	string or integer	Yes

POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/items

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
  });

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
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
  });

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 Name	Field Type	Required
email	string	Yes

POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/contacts

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
  });

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 Name

Field Type

Required

address

object

Yes

Field Name	Field Type	Required
full_name	string	Yes
telephone	string or number	Yes
address_1	string	Yes
address_2	string	No
city	string	Yes
province	string	Yes
country	string	Yes
postcode	string	Yes

type

string (shipping, billing)

Yes

POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/addresses

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
  });

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 Name	Field Type	Required
method_code	string	Yes
method_name	string	Yes

POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingMethods

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
  });

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 Name	Field Type	Required
method_code	string	Yes
method_name	string	Yes

POST/api/cart/363ba97f-8be7-4be9-be3f-a9f341f2b89f/paymentMethods

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
  });

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
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
  });

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 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

Overview​

Endpoints​

Create a New Cart​

Add Item to Cart​

Remove Item from Cart​

Add Customer Information​

Add Address​

Add Shipping Method​

Add Payment Method​

Get Cart​

Error Handling​

Checkout Process Flow​

Best Practices​

Overview

Endpoints

Create a New Cart

Add Item to Cart

Remove Item from Cart

Add Customer Information

Add Address

Add Shipping Method

Add Payment Method

Get Cart

Error Handling

Checkout Process Flow

Best Practices