Shopping Basket

The shopping basket is a server-side entity identified by a string ID. Baskets can be anonymous or linked to an authenticated user.

Basket Lifecycle

Create a Basket

POST /api/storefront/basket/{basketId}

The basketId is a client-generated string (e.g., a UUID). If the user is authenticated, the basket is automatically linked to their account.

// Generate a basket ID on the client
const basketId = crypto.randomUUID();
await fetch(`/api/storefront/basket/${basketId}`, { method: 'POST' });

Get Basket

GET /api/storefront/basket/{basketId}

Response:

{
  "id": "basket-uuid",
  "items": [
    {
      "id": "item-guid",
      "productVariantId": "variant-guid",
      "productName": "Classic T-Shirt",
      "variantName": "White / M",
      "sku": "CT-WHT-M",
      "quantity": 2,
      "unitPrice": 29.99,
      "lineTotal": 59.98,
      "imageUrl": "https://api.example.com/media/product-images/ct-white.png"
    }
  ],
  "subtotal": 59.98,
  "appliedPromotions": [
    {
      "promotionId": "guid",
      "name": "Summer Sale 20%",
      "discountAmount": 12.00,
      "badgeText": "SUMMER SALE"
    }
  ],
  "totalPromotionDiscount": 12.00,
  "hasFreeShipping": false,
  "discountCode": null,
  "discountAmount": 0
}

Automatic Promotions

Every time you fetch a basket, the API evaluates all active promotions and returns the applied discounts. No extra API call needed.

Get User's Basket

GET /api/storefront/basket/user
Authorization: Bearer <token>

Returns the basket linked to the authenticated user's account.

Add Item

POST /api/storefront/basket/{basketId}/items
Content-Type: application/json

{
  "productVariantId": "variant-guid",
  "quantity": 1
}

Update Item Quantity

PUT /api/storefront/basket/{basketId}/items/{itemId}
Content-Type: application/json

{
  "quantity": 3
}

Remove Item

DELETE /api/storefront/basket/{basketId}/items/{itemId}

Apply Discount Code

POST /api/storefront/basket/{basketId}/discount-code
Content-Type: application/json

{
  "code": "WELCOME10"
}

Discount codes are separate from automatic promotions. A basket can have both:

• Automatic promotions — evaluated on every basket fetch (no code needed)
• Discount code — manually applied by the user (one at a time)

Remove Discount Code

DELETE /api/storefront/basket/{basketId}/discount-code

Basket Merge (Login)

When an anonymous user logs in, you may want to merge their anonymous basket with their existing user basket. Handle this in your frontend:

1. Guest browses and adds items → anonymous basket (client-generated ID)
2. Guest logs in → fetch user's existing basket via GET /basket/user
3. If both have items, either:
   • Replace: Use the user's basket, discard anonymous one
   • Merge: Add anonymous basket items to user basket via POST /basket/{userBasketId}/items

The API doesn't auto-merge — this gives you control over the UX.