Cart API Reference

Manage shopping carts, items, discounts, and cart-related operations in the checkout system.

Base Path: /api/cart

Overview

The Cart API provides comprehensive endpoints for managing shopping carts including creation, item management, discount application, and cart merging. Supports both authenticated and guest carts.

Key Operations

API Endpoints

POST /api/cart

Create Cart

Creates a new shopping cart for authenticated or guest user.

Authentication

Bearer Token (optional)

Request Body

{
  "customerId": "cust_123",
  "currency": "USD",
  "cartType": "authenticated"
}

Response

{
  "cartId": "cart_789",
  "customerId": "cust_123",
  "currency": "USD",
  "items": [],
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/cart/{cartId}

Get Cart

Gets cart details with all items and totals.

Authentication

Bearer Token or Service Token

Path Parameters

Parameter Type
cartId string

Response

{
  "cartId": "cart_789",
  "customerId": "cust_123",
  "currency": "USD",
  "items": [
    {
      "cartItemId": "item_1",
      "offerId": "offer_456",
      "quantity": 2,
      "price": 99.99,
      "amount": 199.98
    }
  ],
  "discounts": [
    {
      "code": "SAVE10",
      "type": "percentage",
      "value": 10,
      "amount": 19.99
    }
  ],
  "subtotal": 199.98,
  "discount": 19.99,
  "tax": 18.00,
  "total": 197.99,
  "createdAt": "2026-06-02T10:30:00Z"
}
DELETE /api/cart/{cartId}

Delete Cart

Deletes a shopping cart and all items.

Authentication

Bearer Token or Service Token

Path Parameters

Parameter Type
cartId string

Response

{
  "success": true,
  "message": "Cart deleted"
}
GET /api/cart/customer/{customerId}

Get Cart by Customer

Gets active cart for a customer.

Authentication

Bearer Token or Service Token

Path Parameters

Parameter Type
customerId string

Response

{
  "cartId": "cart_789",
  "customerId": "cust_123",
  "items": [],
  "total": 0,
  "createdAt": "2026-06-02T10:30:00Z"
}
POST /api/cart/merge

Merge Carts

Merges guest cart items into authenticated customer cart.

Authentication

Bearer Token

Request Body

{
  "guestCartId": "cart_guest_123",
  "customerCartId": "cart_789",
  "mergeStrategy": "add"
}

Response

{
  "cartId": "cart_789",
  "itemsMerged": 3,
  "total": 299.97,
  "mergedAt": "2026-06-02T10:35:00Z"
}
POST /api/cart/{cartId}/items

Add Item to Cart

Adds a product offer to the cart.

Authentication

Bearer Token or Service Token

Request Body

{
  "offerId": "offer_456",
  "quantity": 2,
  "price": 99.99
}

Response

{
  "cartItemId": "item_1",
  "offerId": "offer_456",
  "quantity": 2,
  "price": 99.99,
  "amount": 199.98,
  "addedAt": "2026-06-02T10:30:00Z"
}
PUT /api/cart/{cartId}/items/{itemId}

Update Cart Item

Updates quantity or price of a cart item.

Authentication

Bearer Token or Service Token

Request Body

{
  "quantity": 3,
  "price": 99.99
}

Response

{
  "cartItemId": "item_1",
  "offerId": "offer_456",
  "quantity": 3,
  "amount": 299.97,
  "updatedAt": "2026-06-02T10:35:00Z"
}
DELETE /api/cart/{cartId}/items/{itemId}

Remove Item from Cart

Removes a specific item from the cart.

Authentication

Bearer Token or Service Token

Response

{
  "success": true,
  "message": "Item removed from cart"
}
POST /api/cart/{cartId}/discounts

Apply Discount Code

Applies a discount or promotional code to the cart.

Authentication

Bearer Token or Service Token

Request Body

{
  "code": "SAVE10",
  "type": "percentage"
}

Response

{
  "code": "SAVE10",
  "type": "percentage",
  "value": 10,
  "amount": 19.99,
  "newTotal": 180.99,
  "appliedAt": "2026-06-02T10:40:00Z"
}
DELETE /api/cart/{cartId}/discounts/{code}

Remove Discount Code

Removes a discount code from the cart.

Authentication

Bearer Token or Service Token

Response

{
  "success": true,
  "message": "Discount removed",
  "newTotal": 199.98
}

Error Responses

Code HTTP Status Description
CART_NOT_FOUND 404 Cart does not exist
ITEM_NOT_FOUND 404 Cart item does not exist
INVALID_DISCOUNT 400 Discount code is invalid or expired
INSUFFICIENT_INVENTORY 400 Not enough stock for requested quantity

Quick Links

← Back to Overview ← Invoices API Receipts API → Try the Playground