Cart & Wishlist

The CartWishlistService class (accessed via client.cartWishlist) manages shopping carts for both authenticated and anonymous users, along with customer wishlists.

Overview

The cart and wishlist APIs support full variant tracking and a unified media gallery system. This enables customers to save specific product selections (color, size, etc.) with accurate pricing, real-time stock levels, and variant-specific images.

Sandbox isolation: Cart and wishlist items created with a tybrite_pk_test_* or tybrite_sk_test_* key are stored in the sandbox environment and are never visible to production keys. Every response includes a Tybrite-Environment: sandbox | production header confirming which environment resolved.

Security Model

Cart and wishlist endpoints accept publishable keys, so a leaked publishable key alone is not enough to access another customer’s cart. When the request claims a customer_id (query or body), Galactic Core requires a customer identity — supply either xAuthToken (the customer’s session JWT from client.authentication.login or verifyOtp) or xExternalAuth (a bring-your-own-auth signed assertion, if your store runs its own identity provider); provide one, not both. The resolved customer must match the claimed customer_id, otherwise the request returns 403 forbidden. Anonymous (session-only) carts skip this check and rely on the secrecy of X-Session-Id.

All wishlist endpoints (and mergeCart) always require a customer identity (xAuthToken or xExternalAuth) because they are inherently customer-scoped. Only cart reads/writes that omit customer_id and rely solely on xSessionId may proceed unauthenticated.

Cart Management

`getCart`

Retrieve the current contents of a cart. This method supports both logged-in customers and anonymous guest sessions.

// Anonymous (no auth token needed)
const guestCart = await client.cartWishlist.getCart({
  xSessionId: 'guest-uuid-123'
});

// Authenticated (token required — JWT must resolve to customerId)
const cart = await client.cartWishlist.getCart({
  xAuthToken: customerSession.access_token,
  customerId: 'customer-uuid'
});

const firstItem = cart.items[0];
console.log(`Item: ${firstItem.product_name} (${firstItem.variant_name})`);
console.log(`Thumbnail: ${firstItem.thumbnail_url}`);

Response (200)

{
  "items": [
    {
      "id": "09695de2-73ac-45ea-b2cb-76f9751b9846",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "product_name": "Samsung Galaxy Watch 6",
      "variant_name": "Default",
      "variant_attributes": {},
      "product_sku": "SAM-WATCH-6-44-0186",
      "thumbnail_url": "https://cdn.tybritelabs.com/stores/.../primary-1774785167560.jpg",
      "quantity": 2,
      "unit_price": 299.99,
      "selling_price": 299.99,
      "total_price": 599.98,
      "stock_available": 183,
      "has_variants": false
    }
  ]
}

See Response Objects below for the full CartItem shape, including the media[] gallery.

`addToCart`

Add a specific product variant to the cart. If the same variant already exists, its quantity will be incremented.

variant_id is required to specify the exact product selection. For products without variants, use the default variant ID.

// Anonymous Cart (no auth token needed)
await client.cartWishlist.addToCart({
  xSessionId: 'guest-uuid-123',
  requestBody: {
    variant_id: 'variant-uuid',
    quantity: 1
  }
});

// Authenticated Cart (token required)
await client.cartWishlist.addToCart({
  xAuthToken: customerSession.access_token,
  requestBody: {
    variant_id: 'variant-uuid',
    quantity: 1,
    customer_id: 'customer-uuid'
  }
});
// → { items: [...] } — the full updated cart (same shape as getCart)

`updateCartItem`

Update variables for a specific item already in the cart, such as changing the quantity.

// Anonymous (no auth token needed)
await client.cartWishlist.updateCartItem({
  id: 'cart-item-uuid',
  xSessionId: 'guest-uuid-123',
  requestBody: {
    quantity: 5
  }
});

// Authenticated (token required)
await client.cartWishlist.updateCartItem({
  id: 'cart-item-uuid', // The UUID of the item in the cart
  xAuthToken: customerSession.access_token,
  requestBody: {
    quantity: 5,
    customer_id: 'customer-uuid'
  }
});
// → { items: [...] } — the full updated cart with the new quantity + recomputed total_price

`clearCart`

Remove all items from the cart in a single operation.

// Anonymous (no auth token needed)
await client.cartWishlist.clearCart({
  xSessionId: 'guest-uuid-123'
});

// Authenticated (token required)
await client.cartWishlist.clearCart({
  xAuthToken: customerSession.access_token,
  customerId: 'customer-uuid'
});
// → { items: [] } — the now-empty cart

`removeCartItem`

Remove a specific item from the cart.

// Anonymous (no auth token needed)
await client.cartWishlist.removeCartItem({
  id: 'cart-item-uuid',
  xSessionId: 'guest-uuid-123'
});

// Authenticated (token required)
await client.cartWishlist.removeCartItem({
  id: 'cart-item-uuid',
  xAuthToken: customerSession.access_token,
  customerId: 'customer-uuid'
});
// → { items: [...] } — the cart with that item removed

`mergeCart`

Combine an anonymous guest cart with a customer’s permanent cart. Carts are matched by both product_id and variant_id to prevent merging different variants of the same product.

mergeCart always requires xAuthToken — it links a guest session to a customer record, so Galactic Core must verify the caller actually owns that customer.

await client.cartWishlist.mergeCart({
  xAuthToken: customerSession.access_token,
  requestBody: {
    session_id: 'guest-session-uuid',
    customer_id: 'authenticated-customer-uuid'
  }
});
// → { items: [...] } — the merged customer cart (guest lines folded in)

Wishlist Management

All wishlist endpoints require xAuthToken. Wishlists are inherently customer-scoped — there is no anonymous mode. The JWT must resolve to the same customer referenced by customer_id.

`getWishlist`

Retrieve a customer’s saved items, including variant and media details.

const { items } = await client.cartWishlist.getWishlist({
  xAuthToken: customerSession.access_token,
  customerId: 'customer-uuid'
});

Response (200)

{
  "items": [
    {
      "id": "2dac3a23-afec-4b6a-a369-e7bdb1f3bc32",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "product_name": "Samsung Galaxy Watch 6",
      "variant_name": "Default",
      "variant_attributes": {},
      "product_sku": "SAM-WATCH-6-44-0186",
      "product_price": 299,
      "thumbnail_url": "https://cdn.tybritelabs.com/stores/.../primary-1774785167560.jpg",
      "stock_available": 183,
      "has_variants": false
    }
  ]
}

`addToWishlist`

Save a specific product variant for later. Wishlists require an authenticated customer_id.

await client.cartWishlist.addToWishlist({
  xAuthToken: customerSession.access_token,
  requestBody: {
    variant_id: 'variant-uuid',
    customer_id: 'customer-uuid'
  }
});
// → 201 { items: [...] } — the full wishlist including the newly saved item
//   (adding a variant already on the wishlist returns 409)

`removeFromWishlist`

Remove an item from the customer’s wishlist.

await client.cartWishlist.removeFromWishlist({
  id: 'wishlist-item-uuid',
  xAuthToken: customerSession.access_token,
  customerId: 'customer-uuid'
});
// → { items: [...] } — the wishlist with that item removed

`moveWishlistToCart`

An atomic operation that removes an item from the wishlist and adds it to the active cart. This operation preserves the variant_id and performs stock validation.

await client.cartWishlist.moveWishlistToCart({
  xAuthToken: customerSession.access_token,
  requestBody: {
    wishlist_item_id: 'wishlist-item-uuid',
    customer_id: 'customer-uuid',
    quantity: 1
  }
});

Response (200)

{
  "success": true,
  "message": "Item moved from wishlist to cart",
  "removed_wishlist_item_id": "2dac3a23-afec-4b6a-a369-e7bdb1f3bc32",
  "items": [
    {
      "id": "845e8724-a3dc-432c-9771-26a4173ec48c",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "product_name": "Samsung Galaxy Watch 6",
      "variant_name": "Default",
      "product_sku": "SAM-WATCH-6-44-0186",
      "quantity": 1,
      "unit_price": 299.99,
      "selling_price": 299.99,
      "total_price": 299.99
    }
  ]
}

Response Objects

`CartItem` & `WishlistItem`

Both cart and wishlist items include structured data for optimized frontend rendering.

Field	Type	Description
`id`	`uuid`	Item UUID in the cart or wishlist.
`product_id`	`uuid`	The product UUID this item belongs to.
`variant_id`	`uuid`	The specific identifier for the selected variation.
`product_name`	`string`	Name of the product.
`variant_name`	`string`	Display name for the variant (e.g., “Space Gray”).
`variant_attributes`	`object`	JSON attributes like color or size.
`product_sku`	`string`	SKU for the specific variant.
`thumbnail_url`	`string`	Primary image URL, prioritizing variant media.
`media`	`array`	Full gallery of variant-aware images and videos.
`quantity`	`number`	(Cart only) Number of items added.
`unit_price`	`number`	(Cart only) Base price per unit.
`selling_price`	`number`	(Cart only) Actual price including active sales.
`total_price`	`number`	(Cart only) `unit_price × quantity`.
`product_price`	`number`	(Wishlist only) Current price of the variant.
`stock_available`	`number`	Real-time stock count for the variant.
`has_variants`	`boolean`	Whether the product supports variation selection.
`created_at`	`string`	Timestamp of when the item was added.
`environment`	`string`	`production` or `sandbox` — matches the key used to add the item.

{
    "id": "d1de278b-d260-42da-ae4a-8bb5d34477c3",
    "product_id": "b016b91e-8403-44be-80ca-77a2d55e7b2d",
    "variant_id": "6be67ee4-6657-4998-b728-3e99c075c01b",
    "product_name": "Samsung Galaxy S21",
    "variant_name": "Default",
    "variant_attributes": {},
    "product_sku": "SMG-S21-BLK",
    "thumbnail_url": "https://cdn.tybritelabs.com/stores/.../primary-1774785162626.jpg",
    "media": [
        {
            "id": "cb00d540-692d-432e-9661-7757ac998f75",
            "url": "https://cdn.tybritelabs.com/stores/.../primary-1774785162626.jpg",
            "type": "image",
            "alt_text": "Samsung Galaxy S21",
            "position": 0,
            "is_primary": true
        }
    ],
    "quantity": 2,
    "unit_price": 799.99,
    "selling_price": 799.99,
    "total_price": 1599.98,
    "stock_available": 49,
    "has_variants": false,
    "created_at": "2026-04-11T10:54:23Z",
    "updated_at": "2026-04-11T10:54:23Z",
    "environment": "production"
}

{
    "id": "38578dcd-67a7-4adc-9b64-3896d1bd638d",
    "product_id": "b016b91e-8403-44be-80ca-77a2d55e7b2d",
    "variant_id": "6be67ee4-6657-4998-b728-3e99c075c01b",
    "product_name": "Samsung Galaxy S21",
    "variant_name": "Default",
    "variant_attributes": {},
    "product_sku": "SMG-S21-BLK",
    "product_price": 799.99,
    "thumbnail_url": "https://cdn.tybritelabs.com/stores/.../primary-1774785162626.jpg",
    "media": [
        {
            "id": "cb00d540-692d-432e-9661-7757ac998f75",
            "url": "https://cdn.tybritelabs.com/stores/.../primary-1774785162626.jpg",
            "type": "image",
            "alt_text": "Samsung Galaxy S21",
            "position": 0,
            "is_primary": true
        }
    ],
    "stock_available": 49,
    "has_variants": false,
    "created_at": "2026-04-11T10:52:09Z",
    "environment": "production"
}

Core Logic

Stock Validation

Stock checks are enforced against the specific variant during all cart operations. If the requested quantity exceeds stock_available, the API returns an insufficient_stock error code along with the current available count.

Pricing Logic

Prices are calculated at the variant level using the selling_price field. This ensures that different variations (e.g., larger sizes or premium colors) are priced accurately and that active promotions are automatically applied.

Frontend Patterns

Variant Selection & Add to Cart

When a user selects a variant and adds it to their cart, branch on whether you have a stored customer session:

// Read the stored session — set by client.authentication.login / verifyOtp
const customerSession = JSON.parse(localStorage.getItem('tybrite_session') ?? 'null');

const handleAddToCart = async (selectedVariant: Variant, quantity: number) => {
  try {
    if (customerSession?.access_token) {
      // Authenticated path — JWT must resolve to customer_id
      const { items } = await client.cartWishlist.addToCart({
        xAuthToken: customerSession.access_token,
        requestBody: {
          variant_id: selectedVariant.variant_id,
          quantity,
          customer_id: customerSession.customer_id
        }
      });
      // → { items: [...] } — re-render the cart badge from items.length
    } else {
      // Anonymous path — session-only cart
      const { items } = await client.cartWishlist.addToCart({
        xSessionId: sessionId,
        requestBody: {
          variant_id: selectedVariant.variant_id,
          quantity
        }
      });
      // → { items: [...] }
    }
  } catch (error) {
    if (error.code === 'insufficient_stock') {
      alert(`Only ${error.available_stock} items available`);
    }
  }
};

Pro Tip: Use xSessionId for guest users. Tybrite will persist this guest cart until it is either merged via mergeCart (which requires xAuthToken) or cleared.

When a guest logs in, call mergeCart with the freshly minted xAuthToken to fold their guest cart into their customer cart before clearing X-Session-Id.

Response Codes

Code	Meaning
`200`	Success on reads, updates, `clearCart`, and `mergeCart`.
`201`	Success on `addToWishlist` — a new wishlist item was created.
`400`	`insufficient_stock`, missing required fields, or invalid body.
`401`	Missing or invalid `xAuthToken`.
`403`	The customer token does not match the `customer_id` in the request.
`404`	Variant, wishlist item, or cart item not found.
`409`	Item already in wishlist (on `addToWishlist`).

Get Started

Core Commerce

Discovery

Checkout & Logistics

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Overview

Security Model

Cart Management

`getCart`

`addToCart`

`updateCartItem`

`clearCart`

`removeCartItem`

`mergeCart`

Wishlist Management

`getWishlist`

`addToWishlist`

`removeFromWishlist`

`moveWishlistToCart`

Response Objects

`CartItem` & `WishlistItem`

Core Logic

Stock Validation

Pricing Logic

Frontend Patterns

Variant Selection & Add to Cart

Response Codes

​Overview

​Security Model

​Cart Management

​getCart

​addToCart

​updateCartItem

​clearCart

​removeCartItem

​mergeCart

​Wishlist Management

​getWishlist

​addToWishlist

​removeFromWishlist

​moveWishlistToCart

​Response Objects

​CartItem & WishlistItem

​Core Logic

​Stock Validation

​Pricing Logic

​Frontend Patterns

​Variant Selection & Add to Cart

​Response Codes

Overview

Security Model

Cart Management

`getCart`

`addToCart`

`updateCartItem`

`clearCart`

`removeCartItem`

`mergeCart`

Wishlist Management

`getWishlist`

`addToWishlist`

`removeFromWishlist`

`moveWishlistToCart`

Response Objects

`CartItem` & `WishlistItem`

Core Logic

Stock Validation

Pricing Logic

Frontend Patterns

Variant Selection & Add to Cart

Response Codes