Skip to main content
VIZOCHOK’s cart system follows a simple principle: your backend is the source of truth for the cart. The AI manages the shopping experience, but every cart operation goes through your webhook for validation and persistence.

​
Architecture

There are three participants in the cart flow:

SDK Widget

Receives cart_changed events via WebSocket to update the UI. Never talks to your backend directly for cart operations.

VIZOCHOK Backend

AI Agent decides what to add/remove. Calls your webhooks server-to-server for validation.

Your Backend

Source of truth for cart state. Validates operations, checks stock, persists the real cart.

​
Cart Operation Flow

1

Customer requests cart action

Customer says “Add this milk to my cart” in the chat.
2

AI Agent calls your cart webhook

The agent calls add_to_selection(sku="milk-001", qty=1) which sends a POST to your cart_url:
{
  "action": "add",
  "store_id": "store-1",
  "session_id": "user-123",
  "sku": "milk-001",
  "name": "Молоко Lactel 2.5%",
  "quantity": 1,
  "price": 45.90
}
3

Your backend confirms or rejects

Success: {"ok": true}Failure: {"ok": false, "reason": "out_of_stock"}
4

Agent updates state and responds

Agent updates internal cart state, generates a confirmation message, and sends via WebSocket:
  • text_delta / text_end (AI message)
  • event {type: "item_selected", sku, name, ...}
  • cart_changed {action, items[], total}
5

SDK fires onCartChanged callback

Your frontend receives the onCartChanged(cart) callback and updates the cart badge/sidebar.

​
Initial Cart Loading

1

New WebSocket connection

Customer opens the chat widget and connects via WebSocket.
2

VIZOCHOK calls your cart GET webhook

GET https://your-api.com/api/vizochok/cart/items
  ?store_id=store-1&session_id=user-123
3

Your backend returns current cart

{
  "items": [
    {"sku": "bread-01", "name": "Хліб", "price": 32.00, "quantity": 1, "unit": "pcs"},
    {"sku": "butter-05", "name": "Масло", "price": 89.50, "quantity": 1, "unit": "pcs"}
  ]
}
4

AI starts with context

The AI agent starts the conversation knowing the customer already has bread and butter in their cart.
The session_id parameter matches the userId you pass to the SDK widget config, or an auto-generated identifier if userId is not provided. Use this to look up the correct cart on your side.

​
Handling the onCartChanged Event

In your frontend, register the onCartChanged callback to keep your cart UI in sync: 
const widget = new VIZOCHOKWidget({
  apiKey: 'pk_your_public_key',
  storeId: 'your-store-id',
  userId: 'customer-123',

  onCartChanged: (cart) => {
    // cart.action: 'item_selected' | 'item_removed' | 'quantity_updated' | 'cart_cleared'
    // cart.items:  full array of CartItem objects
    // cart.total:  cart total amount

    switch (cart.action) {
      case 'item_selected':
        showToast(`Added ${cart.name} to cart`);
        break;
      case 'item_removed':
        showToast(`Removed ${cart.name} from cart`);
        break;
      case 'quantity_updated':
        showToast(`Updated ${cart.name} quantity to ${cart.quantity}`);
        break;
      case 'cart_cleared':
        showToast('Cart cleared');
        break;
    }

    // Update your cart UI
    updateCartBadge(cart.items.length);
    updateCartTotal(cart.total);
    updateCartItems(cart.items);
  },
});

​
CartItem Structure

Each item in cart.items contains: 
interface CartItem {
  sku: string;         // Product SKU
  name: string;        // Product name
  price: number;       // Unit price
  promo_price?: number; // Promotional price (if on sale)
  brand?: string;      // Brand name
  quantity: number;    // Quantity in cart
}

​
Handling Rejections

When your backend rejects a cart operation (e.g., product is out of stock), the AI handles it gracefully: 
AI: "I'll add that milk to your cart."
        │
        ▼
Your webhook returns:
  {"ok": false, "reason": "out_of_stock"}
        │
        ▼
AI: "Sorry, that milk is currently out of stock.
     Would you like to try a different brand?"
Common rejection reasons:
ReasonWhen to Return
out_of_stockProduct is not available
product_not_foundSKU does not exist in your system
quantity_exceededRequested quantity exceeds stock
missing_skuNo SKU provided in the request
missing_paramsRequired parameters are missing
The AI will suggest alternatives when a product is unavailable, using the same search and recommendation system.

​
Cart Operations

The AI can perform four cart operations through your webhook:
ActionDescriptionRequired Fields
addAdd a product to the cartsku, name, quantity, price
removeRemove a product from the cartsku
update_quantityChange the quantity of an existing itemsku, quantity
clearRemove all items from the cart(none)
For the complete webhook request/response specification, see Cart Webhook.

​
Without Webhooks

If you do not configure cart webhooks, VIZOCHOK still tracks the cart internally during the conversation. However:
  • Cart state is session-only (not persisted to your backend)
  • No stock validation on add
  • The onCartChanged event still fires in the SDK
  • Your frontend would need to reconcile the AI cart with your real cart
For the best experience, we strongly recommend implementing cart webhooks. This ensures the AI always works with real inventory data and the customer’s actual cart state.