Cart API

Manage shopping cart operations including adding items, updating quantities, and preparing for checkout.

Cart Flow

sequenceDiagram
    Client->>API: POST /cart/items (Add to cart)
    API->>API: Validate product & inventory
    API->>Client: Return updated cart
    Client->>API: PUT /cart/items/:id (Update quantity)
    API->>API: Check inventory availability
    API->>Client: Return updated cart
    Client->>API: GET /cart (View cart)
    API->>Client: Return cart with totals
    Client->>API: POST /cart/checkout
    API->>Client: Return checkout session

Endpoints

Get Cart

Retrieve the current user's shopping cart.

Endpoint: GET /cart

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response: 200 OK

{
  "success": true,
  "data": {
    "id": "cart_cm52kg0000000qv0akj8r9w3d",
    "userId": "cm52kg0000000qv0akj8r9w3d",
    "items": [
      {
        "id": "item_1",
        "productId": "prod_abc123",
        "product": {
          "id": "prod_abc123",
          "name": "Wireless Headphones",
          "slug": "wireless-headphones",
          "price": 79.99,
          "images": ["https://example.com/image1.jpg"],
          "stock": 50
        },
        "quantity": 2,
        "price": 79.99,
        "subtotal": 159.98
      }
    ],
    "subtotal": 159.98,
    "tax": 15.99,
    "shipping": 10.00,
    "total": 185.97,
    "itemCount": 2,
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Error Response: 401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Add Item to Cart

Add a product to the shopping cart.

Endpoint: POST /cart/items

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request Body:

{
  "productId": "prod_abc123",
  "quantity": 2,
  "variantId": "variant_xyz" // Optional
}

Response: 201 Created

{
  "success": true,
  "message": "Item added to cart",
  "data": {
    "id": "cart_cm52kg0000000qv0akj8r9w3d",
    "items": [
      {
        "id": "item_1",
        "productId": "prod_abc123",
        "product": {
          "id": "prod_abc123",
          "name": "Wireless Headphones",
          "slug": "wireless-headphones",
          "price": 79.99,
          "images": ["https://example.com/image1.jpg"],
          "stock": 50
        },
        "quantity": 2,
        "price": 79.99,
        "subtotal": 159.98
      }
    ],
    "subtotal": 159.98,
    "tax": 15.99,
    "shipping": 10.00,
    "total": 185.97,
    "itemCount": 2
  }
}

Error Response: 400 Bad Request

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_STOCK",
    "message": "Requested quantity exceeds available stock"
  }
}

Validation Rules:

productId: Required, must be a valid product ID
quantity: Required, must be a positive integer
variantId: Optional, must be a valid variant ID if provided

Update Cart Item

Update the quantity of an item in the cart.

Endpoint: PUT /cart/items/:id

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Path Parameters:

id: Cart item ID

Request Body:

{
  "quantity": 3
}

Response: 200 OK

{
  "success": true,
  "message": "Cart item updated",
  "data": {
    "id": "cart_cm52kg0000000qv0akj8r9w3d",
    "items": [
      {
        "id": "item_1",
        "productId": "prod_abc123",
        "quantity": 3,
        "price": 79.99,
        "subtotal": 239.97
      }
    ],
    "subtotal": 239.97,
    "tax": 23.99,
    "shipping": 10.00,
    "total": 273.96,
    "itemCount": 3
  }
}

Error Response: 404 Not Found

{
  "success": false,
  "error": {
    "code": "ITEM_NOT_FOUND",
    "message": "Cart item not found"
  }
}

Validation Rules:

quantity: Required, must be a positive integer, cannot exceed stock

Remove Cart Item

Remove an item from the cart.

Endpoint: DELETE /cart/items/:id

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Path Parameters:

id: Cart item ID

Response: 200 OK

{
  "success": true,
  "message": "Item removed from cart",
  "data": {
    "id": "cart_cm52kg0000000qv0akj8r9w3d",
    "items": [],
    "subtotal": 0,
    "tax": 0,
    "shipping": 0,
    "total": 0,
    "itemCount": 0
  }
}

Error Response: 404 Not Found

{
  "success": false,
  "error": {
    "code": "ITEM_NOT_FOUND",
    "message": "Cart item not found"
  }
}

Clear Cart

Remove all items from the cart.

Endpoint: DELETE /cart

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response: 200 OK

{
  "success": true,
  "message": "Cart cleared",
  "data": {
    "id": "cart_cm52kg0000000qv0akj8r9w3d",
    "items": [],
    "subtotal": 0,
    "tax": 0,
    "shipping": 0,
    "total": 0,
    "itemCount": 0
  }
}

Prepare Checkout

Prepare the cart for checkout and create a checkout session.

Endpoint: POST /cart/checkout

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request Body:

{
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1-555-0100",
    "email": "[email protected]",
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postalCode": "10001"
  },
  "billingAddressId": "addr_xyz123",
  "shippingMethodId": "ship_standard"
}

Response: 200 OK

{
  "success": true,
  "message": "Checkout session created",
  "data": {
    "checkoutId": "checkout_abc123",
    "cart": {
      "items": [
        {
          "id": "item_1",
          "productId": "prod_abc123",
          "quantity": 2,
          "price": 79.99,
          "subtotal": 159.98
        }
      ],
      "subtotal": 159.98,
      "tax": 15.99,
      "shipping": 10.00,
      "total": 185.97
    },
    "shippingAddress": {
      "id": "addr_xyz123",
      "name": "John Doe",
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "US"
    },
    "billingAddress": {
      "id": "addr_xyz123",
      "name": "John Doe",
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "US"
    },
    "shippingMethod": {
      "id": "ship_standard",
      "name": "Standard Shipping",
      "cost": 10.00,
      "estimatedDays": "5-7"
    },
    "expiresAt": "2024-01-01T01:00:00.000Z"
  }
}

Error Response: 400 Bad Request

{
  "success": false,
  "error": {
    "code": "EMPTY_CART",
    "message": "Cannot checkout with an empty cart"
  }
}

Validation Rules:

shippingAddress: Required, must be a valid address object
billingAddressId: Required, must be a valid address ID
shippingMethodId: Required, must be a valid shipping method ID
Cart must not be empty
All items must be in stock

Error Codes

Code	Description
`UNAUTHORIZED`	Authentication required or token invalid
`ITEM_NOT_FOUND`	Cart item not found
`PRODUCT_NOT_FOUND`	Product not found
`INSUFFICIENT_STOCK`	Requested quantity exceeds available stock
`INVALID_QUANTITY`	Quantity must be a positive integer
`EMPTY_CART`	Cart is empty
`CHECKOUT_VALIDATION_FAILED`	Checkout validation failed

Best Practices

Always check stock availability before adding items to cart
Validate cart before checkout to ensure all items are still available
Handle cart expiration - checkout sessions expire after 1 hour
Update totals in real-time when cart items change
Implement optimistic updates for better user experience
Clear cart after successful order to prevent duplicate orders

Rate Limits

Cart operations: 100 requests per minute per user
Checkout: 10 requests per minute per user

Exceeding rate limits will result in a 429 Too Many Requests response.

Cart API

On this page