Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wppconnect-team/wa-js/llms.txt

Use this file to discover all available pages before exploring further.

The WPP.cart module lets you programmatically manage shopping carts that belong to individual WhatsApp Business chat sessions. A cart is tied to a specific chatId — the JID of the business you are chatting with — and persists in WhatsApp Web’s internal CartStore until it is submitted or cleared.
Carts are scoped to a specific business chat session. The chatId you pass to every function must be the WhatsApp ID of the business contact (e.g. 5521985625689@c.us), not a group or broadcast list. A cart cannot be submitted to your own account.

​
Reading the cart

​
get(wid)

Returns the current cart model for a given business chat. This is a synchronous function — it reads directly from CartStore without a network request.
​
wid
string
required
The WhatsApp ID of the business chat whose cart you want to retrieve.
const cart = WPP.cart.get('5521985625689@c.us');
if (cart) {
  console.log('Items in cart:', cart.itemCount);
}
​
returns
CartModel | undefined
The cart model if a cart exists for this chat, or undefined if none has been created yet.

​
getThumbFromCart(wid)

Generates a base64 thumbnail image from the first item in the cart. This is the same thumbnail that appears in the order message preview when you call submit. Returns an empty string if no cart, no items, or no image is found.
​
wid
string
required
The WhatsApp ID of the business chat.
const thumb = await WPP.cart.getThumbFromCart('5521985625689@c.us');
if (thumb) {
  console.log('Thumbnail (base64):', thumb.substring(0, 60) + '...');
}
​
returns
Promise<string>
A base64-encoded image string, or an empty string if a thumbnail cannot be generated.

​
Modifying the cart

​
add(chatId, products)

Adds one or more products to the cart for a business chat. Each product is fetched from the catalog using getProductById before being added, so the catalog must be accessible. If a product is already in the cart, its quantity is updated to the value you provide.
​
chatId
string
required
The WhatsApp ID of the business chat.
​
products
object[]
required
const cart = await WPP.cart.add('5521985625689@c.us', [
  { id: '6104203702939361', qnt: 2 },
  { id: '6104289702939362', qnt: 1 },
]);
console.log('Cart now has', cart?.itemCount, 'items');
​
returns
Promise<CartModel | undefined>
The updated cart model, or undefined if the cart cannot be found after the update.

​
update(chatId, productId, options)

Updates the quantity of a single product already in the cart. Internally this calls add with the new quantity, so it will also add the product if it is not yet in the cart.
​
chatId
string
required
The WhatsApp ID of the business chat.
​
productId
string
required
The ID of the product to update.
​
options
object
required
const cart = await WPP.cart.update(
  '5521985625689@c.us',
  '6104203702939361',
  { quantity: 5 }
);
​
returns
Promise<CartModel | undefined>
The updated cart model.

​
remove(chatId, productId)

Removes a single product from the cart. The rest of the cart items are preserved.
​
chatId
string
required
The WhatsApp ID of the business chat.
​
productId
string
required
The ID of the product to remove.
const cart = await WPP.cart.remove(
  '5521985625689@c.us',
  '6104203702939361'
);
console.log('Remaining items:', cart?.itemCount);
​
returns
Promise<CartModel | undefined>
The cart model after removal.

​
clear(wid)

Empties all items from the cart. Throws a WPPError with code cart_not_have_products if the cart is already empty or does not exist.
​
wid
string
required
The WhatsApp ID of the business chat whose cart you want to clear.
try {
  await WPP.cart.clear('5521985625689@c.us');
  console.log('Cart cleared.');
} catch (err) {
  if (err.code === 'cart_not_have_products') {
    console.log('Cart was already empty.');
  }
}
​
returns
Promise<void>
Resolves when the cart has been emptied.

​
Submitting the cart

​
submit(wid, msg?, options?)

Submits the current cart as an order message to the business chat. This creates a WhatsApp order, sends an order-type message to the conversation, and then clears the cart automatically. The returned value is the sent message object.
You cannot submit an order to your own account — the function throws can_not_submit_order_to_yourself if wid matches your own WhatsApp ID. The cart must also contain at least one product; an empty cart throws cart_not_have_products.
​
wid
string
required
The WhatsApp ID of the business chat to send the order to.
​
msg
string
An optional custom message to include with the order. If omitted, the cart’s stored message is used.
​
options
SendMessageOptions
Optional send options forwarded to the underlying message sending function (e.g. quotedMsg).
// Submit with a custom note
const orderMsg = await WPP.cart.submit(
  '5521985625689@c.us',
  'Please deliver before 5 PM.'
);
console.log('Order message ID:', orderMsg.id);

// Submit without a custom message
const orderMsg = await WPP.cart.submit('5521985625689@c.us');
​
returns
Promise<any>
The sent message object retrieved by message ID after the order is dispatched.

​
Full cart-to-order workflow

The following example walks through a complete purchase flow: browsing a catalog, building a cart, and submitting an order. 
const BUSINESS_JID = '5521985625689@c.us';

// Step 1 — Browse the business catalog
const products = await WPP.catalog.getProducts(BUSINESS_JID, 10);
console.log('Available products:', products.map((p) => p.name));

// Step 2 — Add items to the cart
await WPP.cart.add(BUSINESS_JID, [
  { id: products[0].id, qnt: 2 },
  { id: products[1].id, qnt: 1 },
]);

// Step 3 — Adjust a quantity if needed
await WPP.cart.update(BUSINESS_JID, products[0].id, { quantity: 3 });

// Step 4 — Preview the cart thumbnail
const thumb = await WPP.cart.getThumbFromCart(BUSINESS_JID);
console.log('Cart thumbnail available:', thumb.length > 0);

// Step 5 — Submit the order
const orderMessage = await WPP.cart.submit(
  BUSINESS_JID,
  'Hi! Please process this order at your earliest convenience.'
);
console.log('Order sent. Message ID:', orderMessage.id);
After submit succeeds the cart is automatically cleared. You do not need to call clear manually. Use clear only when you want to discard a cart without sending an order.

​
Error codes

Thrown by add, update, and remove when required arguments (chatId, productId, options.quantity) are missing or falsy.
Thrown by clear and submit when the cart does not exist or contains no items.
Thrown by submit when the wid matches the currently logged-in account’s own WhatsApp ID.
Thrown by submit after dispatch if the created order did not receive a valid order ID from WhatsApp’s servers.

Build docs developers (and LLMs) love

Get started for freeTalk to us