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"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/carts

fetch('https://<your domain>/api/carts', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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"
  --data-raw "<JSON DATA>"
  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',
  },
  body: <JSON DATA>
})
  .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/carts/{id}/contacts

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/carts/{id}/contacts

fetch('https://<your domain>/api/carts/{id}/contacts', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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.

The payload uses the Address Format Registry vocabulary (one set of column names shared by customer, cart and order addresses). A logged-in customer can also reuse a saved address by sending customerAddressUuid instead of the fields: the row is copied verbatim, extra included.

Request Schema (application/json)

Field Name

Field Type

Required

address

object

Yes

Field Name	Field Type	Required
recipient	string or null	No
given_name	string or null	No
family_name	string or null	No
organization	string or null	No
address_line_1	string or null	No
address_line_2	string or null	No
address_line_3	string or null	No
dependent_locality	string or null	No
locality	string or null	No
administrative_area	string or null	No
postal_code	string or null	No
sorting_code	string or null	No
country	string	Yes
telephone	string or null	No
extra	object or null	No
customerAddressUuid	string	No

type

string (shipping, billing)

Yes

POST/api/carts/{id}/addresses

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/carts/{id}/addresses

fetch('https://<your domain>/api/carts/{id}/addresses', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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",
  "recipient": "John Doe",
  "given_name": null,
  "family_name": null,
  "organization": null,
  "address_line_1": "1234 Main St",
  "address_line_2": null,
  "address_line_3": null,
  "dependent_locality": null,
  "locality": "Cupertino",
  "administrative_area": "US-CA",
  "postal_code": "95014",
  "sorting_code": null,
  "country": "US",
  "telephone": "+14085551234",
  "extra": {}
}
}

Which keys are required, which patterns apply and which region keys are accepted depend on the country's address schema: country is the only key the payload schema requires, and the service then validates the whole address against addressSchema(country) — the same schema the storefront form renders from. A key that is neither one of the columns above nor a registered extra field is rejected with unknown_field. See the Address formats guide for the field vocabulary, region keys and the settings that change what is required.

Validation failures answer 400 with one entry per field:

{
  "error": {
    "status": 400,
    "message": "Invalid address",
    "errors": [
      { "field": "postal_code", "code": "pattern", "message": "ZIP code is not valid" },
      { "field": "administrative_area", "code": "region_invalid", "message": "State is not a valid region" }
    ]
  }
}

code is one of required, pattern, region_invalid, type, unknown_field or country_not_allowed; message is already translated into the request locale.

A shipping address must also be in a country the store ships to (a country covered by a shipping zone and in the sell-to list); otherwise the error code is country_not_allowed.

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

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

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/carts/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingMethods

fetch('https://<your domain>/api/carts/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingMethods', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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

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

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/carts/363ba97f-8be7-4be9-be3f-a9f341f2b89f/paymentMethods

fetch('https://<your domain>/api/carts/363ba97f-8be7-4be9-be3f-a9f341f2b89f/paymentMethods', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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"
  }
}
}

Add Shipping Note

Specifies the shipping note to be added to the order.

Request Schema (application/json)

Field Name	Field Type	Required
note	string	Yes

POST/api/carts/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingNotes

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/carts/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingNotes

fetch('https://<your domain>/api/carts/363ba97f-8be7-4be9-be3f-a9f341f2b89f/shippingNotes', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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": {
    "note": "Please deliver between 5 PM and 7 PM"
  }
}

Update Cart Item Quantity

Updates the quantity of an item in the cart. Supports both increasing and decreasing quantities.

Request Schema (application/json)

Field Name	Field Type	Required
qty	string or integer	Yes
action	string (increase, decrease)	Yes

PATCH/api/cart/{cart_id}/items/{item_id}

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/cart/{cart_id}/items/{item_id}

fetch('https://<your domain>/api/cart/{cart_id}/items/{item_id}', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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",
    "qty": 3,
    "final_price": 823,
    "total": 2469
  }
}
}

Add Item to My Cart

Adds an item to the currently authenticated customer's cart. This is a convenience endpoint that automatically resolves the customer's active cart.

Request Schema (application/json)

Field Name	Field Type	Required
sku	string	Yes
qty	string or integer	Yes

POST/api/cart/mine/items

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/cart/mine/items

fetch('https://<your domain>/api/cart/mine/items', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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": 1139,
    "uuid": "553ba97f-8be7-4be9-be3f-a9f341f2b89f",
    "product_sku": "PROD-001",
    "qty": 1,
    "final_price": 49.99
  }
}
}

Remove Item from My Cart

Removes a specific item from the currently authenticated customer's cart.

Request Schema (application/json)

No request body required

DELETE/api/cart/mine/items/{item_id}

cURL
JavaScript

curl
  -H "Accept: application/json"
  https://<your domain>/api/cart/mine/items/{item_id}

fetch('https://<your domain>/api/cart/mine/items/{item_id}', {
  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": 1139,
    "uuid": "553ba97f-8be7-4be9-be3f-a9f341f2b89f"
  }
}
}

Update Item Quantity in My Cart

Updates the quantity of an item in the currently authenticated customer's cart.

Request Schema (application/json)

Field Name	Field Type	Required
qty	string or integer	Yes
action	string (increase, decrease)	Yes

PATCH/api/cart/mine/items/{item_id}

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/cart/mine/items/{item_id}

fetch('https://<your domain>/api/cart/mine/items/{item_id}', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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": 1139,
    "uuid": "553ba97f-8be7-4be9-be3f-a9f341f2b89f",
    "qty": 2
  }
}
}

Checkout Cart

Initiates the checkout process for a cart, creating an order.

Request Schema (application/json)

Field Name	Field Type	Required
cart_id	string	Yes

POST/api/carts/{cart_id}/checkout

cURL
JavaScript

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/carts/{cart_id}/checkout

fetch('https://<your domain>/api/carts/{cart_id}/checkout', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .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": {
  "order_id": 2070,
  "uuid": "7afebbbd-69f6-4e2c-84c5-5b899173b867",
  "order_number": "12070"
}
}

Get Cart Data with GraphQL

EverShop uses GraphQL for querying cart data. For detailed information on how to query carts, refer to the GraphQL API documentation.

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​

Add Shipping Note​

Update Cart Item Quantity​

Add Item to My Cart​

Remove Item from My Cart​

Update Item Quantity in My Cart​

Checkout Cart​

Get Cart Data with GraphQL​

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

Add Shipping Note

Update Cart Item Quantity

Add Item to My Cart

Remove Item from My Cart

Update Item Quantity in My Cart

Checkout Cart

Get Cart Data with GraphQL