Get Cart Items

Overview

Retrieve all items currently in the shopping cart. This endpoint works for both authenticated users and guest users, automatically managing cart data based on the session type.

Endpoint

GET /v1/cart

Authentication

This endpoint requires authentication via the x-api-key header. Guest users will automatically receive a guest token for cart persistence.

Request

Headers

Header	Type	Required	Description
`x-api-key`	string	Yes	Your API authentication key

Example Request

async function getCart() {
  const response = await fetch('https://api.yourstore.com/v1/cart', {
    method: 'GET',
    headers: {
      'x-api-key': process.env.BACKEND_API_KEY,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch cart');
  }

  // Store guest token if present
  const guestToken = response.headers.get('x-guest-token');
  if (guestToken) {
    // Store this token for future requests
    localStorage.setItem('guest_token', guestToken);
  }

  const cartItems = await response.json();
  return cartItems;
}

interface CartItem {
  id: string;
  productId: string;
  quantity: number;
  price: number;
  product: {
    name: string;
    image: string;
  };
}

async function getCart(): Promise<CartItem[]> {
  const response = await fetch('https://api.yourstore.com/v1/cart', {
    method: 'GET',
    headers: {
      'x-api-key': process.env.BACKEND_API_KEY!,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch cart');
  }

  // Store guest token if present
  const guestToken = response.headers.get('x-guest-token');
  if (guestToken) {
    localStorage.setItem('guest_token', guestToken);
  }

  const cartItems: CartItem[] = await response.json();
  return cartItems;
}

Server-Side Example (Next.js)

import { cookieManager } from '@/lib/auth-tools';

export async function getCartItems() {
  const headers = await cookieManager.buildApiHeaders();
  
  const response = await fetch('https://api.yourstore.com/v1/cart', {
    method: 'GET',
    headers,
    cache: 'no-store'
  });

  if (!response.ok) {
    throw new Error('Failed to fetch cart');
  }

  await cookieManager.handleApiResponse(response);
  return response.json();
}

import { cookieManager } from '@/lib/auth-tools';

interface CartItem {
  id: string;
  productId: string;
  quantity: number;
  price: number;
}

export async function getCartItems(): Promise<CartItem[]> {
  const headers = await cookieManager.buildApiHeaders();
  
  const response = await fetch('https://api.yourstore.com/v1/cart', {
    method: 'GET',
    headers,
    cache: 'no-store'
  });

  if (!response.ok) {
    throw new Error('Failed to fetch cart');
  }

  await cookieManager.handleApiResponse(response);
  return response.json();
}

Response

Success Response (200)

Returns an array of cart items with product details.

[
  {
    "id": "cart_123",
    "productId": "prod_456",
    "quantity": 2,
    "price": 29.99,
    "product": {
      "name": "Wireless Headphones",
      "image": "https://example.com/images/headphones.jpg",
      "description": "Premium wireless headphones"
    }
  }
]

Error Responses

Status Code	Description
`401`	Invalid or missing API key
`422`	Invalid input data
`500`	Failed to get items from cart

Guest Token Management: When a guest user first interacts with the cart, the API returns an x-guest-token header. Store this token and include it in subsequent requests using the x-guest-token header to maintain cart persistence.

Cart Merging: When a guest user signs in, their guest cart will be merged with their authenticated cart using the /v1/auth/merge-guest-data endpoint.