Shopping Cart API

The Shopping Cart API manages temporary and persistent shopping sessions. Our engine performs automatic hydration, meaning every time you modify the cart, we return the full product details (images, titles, and current prices) to keep your UI reactive without extra fetches.

The Cart Lifecycle

1 Create a new cart or retrieve an existing one linked to the shopper's account.
2 Every update returns a full snapshot of items, including product metadata and subtotals.
3 When a shopper logs in, anonymous items are merged into their cloud-saved cart automatically.

01. Cart Initialization

Initializes a new shopping session. If the X-Customer-Token is present, the API will attempt to retrieve the customer's last active cart from the database instead of creating a new one.

POST /v1/cart

HEADERS ONLY

X-Customer-TokenOptional. If provided, Elective will re-use the existing cart linked to the shopper profile.

Implementation

const createCart = async () => {
  const res = await fetch('https://api.electivecommerce.com/v1/cart', {
    method: 'POST',
    headers: { 
      'Authorization': 'Bearer pk_live_...',
      'X-Customer-Token': localStorage.getItem('shopper_token') || '' // Optional
    }
  });

  const data = await res.json();
  if (data.success) {
    localStorage.setItem('active_cart_id', data.cartId);
  }
};

02. Adding Items

Adds a variant to the specific cart. If the variantId already exists in the cart, our engine will sum the quantities automatically.

POST /v1/cart/:id/items

JSON BODY

variantId (uuid)Required. The unique identifier of the product variant.
quantity (number)Required. Amount to add. Minimum of 1.

Implementation

const addToCart = async (variantId, quantity = 1) => {
  const cartId = localStorage.getItem('active_cart_id');
  const res = await fetch(`https://api.electivecommerce.com/v1/cart/${cartId}/items`, {
    method: 'POST',
    headers: { 
      'Content-Type': 'application/json',
      'Authorization': 'Bearer pk_live_...',
      'X-Customer-Token': localStorage.getItem('shopper_token') || ''
    },
    body: JSON.stringify({ variantId, quantity })
  });

  const { success, cart } = await res.json();
  if (success) {
    console.log('New Subtotal:', cart.subtotal);
  }
};

03. Quantity & Removal

Use PUT to set an absolute quantity for a variant (perfect for number inputs) and DELETE to remove an item entirely from the session.

Implementation: Set Quantity

const updateQuantity = async (variantId, newQuantity) => {
  const cartId = localStorage.getItem('active_cart_id');
  const res = await fetch(`https://api.electivecommerce.com/v1/cart/${cartId}/items`, {
    method: 'PUT',
    headers: { 
      'Content-Type': 'application/json',
      'Authorization': 'Bearer pk_live_...',
      'X-Customer-Token': localStorage.getItem('shopper_token') || ''
    },
    body: JSON.stringify({ variantId, quantity: newQuantity })
  });

  return await res.json();
};

Implementation: Remove

const removeFromCart = async (variantId) => {
  const cartId = localStorage.getItem('active_cart_id');
  await fetch(`https://api.electivecommerce.com/v1/cart/${cartId}/items`, {
    method: 'DELETE',
    headers: { 
      'Content-Type': 'application/json',
      'Authorization': 'Bearer pk_live_...',
      'X-Customer-Token': localStorage.getItem('shopper_token') || ''
    },
    body: JSON.stringify({ variantId })
  });
};

The Response Payload

Every modification endpoint returns a hydrated cart. This object includes the subtotal and an items array where each element contains the full product metadata.

"items": [ { "title": "Red T-Shirt", "price": 25.00, "image_url": "...", "product": { "slug": "t-shirt", ... } } ]

Cart Errors

Common errors encountered when managing shopping sessions.

Status	Code	Description
404	NOT_FOUND	Cart ID has expired or variant was deleted.
403	FORBIDDEN	Attempted to modify a cart belonging to a different customer.