Cart Webhook

The cart webhook is called when the AI assistant performs a cart operation on behalf of the customer. Your endpoint receives the operation details and returns a success/failure response.

Request Format

Method: POST Headers:

Header	Value
`Content-Type`	`application/json`
`X-VIZOCHOK-Signature`	`sha256=<hex_digest>`
`X-VIZOCHOK-Timestamp`	Unix timestamp (seconds)

Body:

{
  "action": "add",
  "store_id": "store-1",
  "session_id": "user-123",
  "sku": "milk-001",
  "name": "Молоко Lactel 2.5%",
  "quantity": 1,
  "price": 45.90
}

Common Fields

string

required

The cart operation: "add", "remove", "update_quantity", or "clear".

string

required

Store identifier.

string

required

Session/user identifier. Matches the userId from the widget config, or an auto-generated ID if none was provided. Use this to look up the correct cart.

Actions

Add

Add a product to the cart.

{
  "action": "add",
  "store_id": "store-1",
  "session_id": "user-123",
  "sku": "milk-001",
  "name": "Молоко Lactel 2.5%",
  "quantity": 1,
  "price": 45.90
}

string

required

Product SKU to add.

string

Product name (for convenience — you can ignore this and look up by SKU).

number

Quantity to add. Defaults to 1 if not provided.

number

Price as known by the AI (from the last products webhook call). You may use this or look up the current price yourself.

Remove

Remove a product from the cart.

{
  "action": "remove",
  "store_id": "store-1",
  "session_id": "user-123",
  "sku": "milk-001"
}

string

required

Product SKU to remove.

Update Quantity

Change the quantity of an existing cart item.

{
  "action": "update_quantity",
  "store_id": "store-1",
  "session_id": "user-123",
  "sku": "milk-001",
  "quantity": 3
}

string

required

Product SKU to update.

number

required

New quantity for the product.

Clear

Remove all items from the cart.

{
  "action": "clear",
  "store_id": "store-1",
  "session_id": "user-123"
}

No additional fields required.

Response Format

Return a JSON object with ok (boolean) and an optional reason on failure:

Success

{"ok": true}

Failure

{"ok": false, "reason": "out_of_stock"}

boolean

required

Whether the operation succeeded.

string

Human-readable reason for failure. The AI uses this to inform the customer and may suggest alternatives.

Common Rejection Reasons

Reason	When to Return	AI Behavior
`out_of_stock`	Product is unavailable	Suggests alternative products
`product_not_found`	SKU does not exist	Informs customer, offers to search again
`quantity_exceeded`	Not enough stock for requested quantity	Suggests a lower quantity
`not_in_cart`	Trying to remove/update an item not in cart	Informs customer
`missing_sku`	No SKU provided	Reports error
`missing_params`	Required parameters missing	Reports error

You can use any string as the reason value. The AI reads the reason and responds contextually. Common, descriptive reasons work best — for example, "max_3_per_customer" would lead the AI to say something like “There’s a limit of 3 per customer for this product.”

Cart GET Endpoint

In addition to the POST webhook for operations, you can implement a GET endpoint to provide the initial cart state when a new conversation starts. Method: GET Query Parameters:

Parameter	Description
`store_id`	Store identifier
`session_id`	Session/user identifier

Response:

{
  "items": [
    {
      "sku": "bread-01",
      "name": "Хліб Столичний",
      "price": 32.00,
      "quantity": 1,
      "unit": "pcs"
    },
    {
      "sku": "butter-05",
      "name": "Масло Президент 200г",
      "price": 89.50,
      "quantity": 1,
      "unit": "pcs",
      "promo_price": 79.90
    }
  ]
}

array

required

Array of cart items.

string

required

Product SKU.

string

required

Product name.

number

required

Unit price.

number

required

Quantity in cart.

string

Unit of measure (e.g., "pcs", "kg"). Defaults to "PCS".

Promotional price, if applicable.

Handler Examples

from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel

app = FastAPI()

class CartWebhookRequest(BaseModel):
    action: str
    store_id: str
    session_id: str
    sku: str | None = None
    name: str | None = None
    quantity: int | None = None
    price: float | None = None


@app.post("/api/vizochok/cart")
async def handle_cart(req: CartWebhookRequest, request: Request):
    body = await request.body()
    verify_signature(request, body)  # See signature verification docs

    cart = get_cart(req.session_id)

    if req.action == "add":
        if not req.sku:
            return {"ok": False, "reason": "missing_sku"}

        product = db.get_product(req.sku)
        if not product or product.stock <= 0:
            return {"ok": False, "reason": "out_of_stock"}

        cart.add_item(
            sku=req.sku,
            name=req.name or product.name,
            price=product.price,  # Use YOUR price, not the one from the request
            quantity=req.quantity or 1,
        )
        return {"ok": True}

    elif req.action == "remove":
        if not req.sku:
            return {"ok": False, "reason": "missing_sku"}
        cart.remove_item(req.sku)
        return {"ok": True}

    elif req.action == "update_quantity":
        if not req.sku or not req.quantity:
            return {"ok": False, "reason": "missing_params"}

        product = db.get_product(req.sku)
        if product and product.stock < req.quantity:
            return {"ok": False, "reason": "quantity_exceeded"}

        cart.update_quantity(req.sku, req.quantity)
        return {"ok": True}

    elif req.action == "clear":
        cart.clear()
        return {"ok": True}

    return {"ok": False, "reason": "unknown_action"}


@app.get("/api/vizochok/cart/items")
async def get_cart_items(store_id: str = "", session_id: str = ""):
    cart = get_cart(session_id)
    return {"items": cart.get_items()}

const express = require('express');
const app = express();

app.use('/api/vizochok', express.json({
  verify: (req, res, buf) => { req.rawBody = buf; }
}));

app.post('/api/vizochok/cart', async (req, res) => {
  try {
    verifySignature(req); // See signature verification docs
  } catch (err) {
    return res.status(401).json({ error: err.message });
  }

  const { action, store_id, session_id, sku, name, quantity, price } = req.body;
  const cart = getCart(session_id);

  switch (action) {
    case 'add': {
      if (!sku) return res.json({ ok: false, reason: 'missing_sku' });

      const product = await db.getProduct(sku);
      if (!product || product.stock <= 0) {
        return res.json({ ok: false, reason: 'out_of_stock' });
      }

      cart.addItem({
        sku,
        name: name || product.name,
        price: product.price,
        quantity: quantity || 1,
      });
      return res.json({ ok: true });
    }

    case 'remove':
      if (!sku) return res.json({ ok: false, reason: 'missing_sku' });
      cart.removeItem(sku);
      return res.json({ ok: true });

    case 'update_quantity':
      if (!sku || !quantity) {
        return res.json({ ok: false, reason: 'missing_params' });
      }
      cart.updateQuantity(sku, quantity);
      return res.json({ ok: true });

    case 'clear':
      cart.clear();
      return res.json({ ok: true });

    default:
      return res.json({ ok: false, reason: 'unknown_action' });
  }
});

app.get('/api/vizochok/cart/items', (req, res) => {
  const { session_id } = req.query;
  const cart = getCart(session_id);
  res.json({ items: cart.getItems() });
});

Best Practices

Always validate stock on add operations. The AI has price data from the last products webhook call, but stock may have changed since then.

Use your own authoritative price when adding items to the cart, not the price field from the webhook request. The price in the request is what VIZOCHOK received from your last products webhook call and may be slightly stale.

Idempotency: If the same add request arrives twice (due to retries), your handler should handle it gracefully — either add the quantity again or deduplicate.
Session mapping: The session_id maps to the userId from the SDK. If no userId was provided, VIZOCHOK generates one per WebSocket connection. Plan your cart storage accordingly.
Response time: Keep responses under 5 seconds (the default timeout). Cart operations should be fast since they are blocking the AI’s response to the customer.

Getting Started

Integration Guides

Widget SDK

Webhooks

Concepts

Request Format

Common Fields

Actions

Add

Remove

Update Quantity

Clear

Response Format

Success

Failure

Common Rejection Reasons

Cart GET Endpoint

Handler Examples

Best Practices

​Request Format

​Common Fields

​Actions

​Add

​Remove

​Update Quantity

​Clear

​Response Format

​Success

​Failure

​Common Rejection Reasons

​Cart GET Endpoint

​Handler Examples

​Best Practices

Request Format

Common Fields

Actions

Add

Remove

Update Quantity

Clear

Response Format

Success

Failure

Common Rejection Reasons

Cart GET Endpoint

Handler Examples

Best Practices