Cart Synchronization

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

Customer requests cart action

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

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
}

Your backend confirms or rejects

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

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}

SDK fires onCartChanged callback

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

Initial Cart Loading

New WebSocket connection

Customer opens the chat widget and connects via WebSocket.

VIZOCHOK calls your cart GET webhook

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

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"}
  ]
}

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 Cart Events in Your Frontend

Register the onCartChanged callback in the widget config to keep your cart UI in sync with AI-managed changes. For the full callback API, event types, and integration examples, see Events & Callbacks.

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 initiates cart action

AI: “I’ll add that milk to your cart.”

Your webhook rejects

Your backend returns: {"ok": false, "reason": "out_of_stock"}

AI suggests alternatives

AI: “Sorry, that milk is currently out of stock. Would you like to try a different brand?”

Common rejection reasons:

Reason	When to Return
`out_of_stock`	Product is not available
`product_not_found`	SKU does not exist in your system
`quantity_exceeded`	Requested quantity exceeds stock
`missing_sku`	No SKU provided in the request
`missing_params`	Required 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:

Action	Description	Required Fields
`add`	Add a product to the cart	`sku`, `name`, `quantity`, `price`
`remove`	Remove a product from the cart	`sku`
`update_quantity`	Change the quantity of an existing item	`sku`, `quantity`
`clear`	Remove 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.

Getting Started

Integration Guides

Widget SDK

Webhooks

Concepts

Cart Synchronization

Architecture

SDK Widget

VIZOCHOK Backend

Your Backend

Cart Operation Flow

Initial Cart Loading

Handling Cart Events in Your Frontend

CartItem Structure

Handling Rejections

Cart Operations

Without Webhooks

​Architecture

SDK Widget

VIZOCHOK Backend

Your Backend

​Cart Operation Flow

​Initial Cart Loading

​Handling Cart Events in Your Frontend

​CartItem Structure

​Handling Rejections

​Cart Operations

​Without Webhooks

Architecture

Cart Operation Flow

Initial Cart Loading

Handling Cart Events in Your Frontend

CartItem Structure

Handling Rejections

Cart Operations

Without Webhooks