Skip to main content
WhatsApp

Catalog & Orders

Turn on the WhatsApp cart and storefront, send catalog and product messages, and the order read API.

Overview

Selling from a WhatsApp catalog takes three steps:

  1. Turn the cart and storefront on for the sending number with commerce settings.
  2. Show products in the chat with a catalog, product or product list message.
  3. Read the orders customers send back from their cart with the Orders API.

The catalog itself (products, prices, images) is managed in Meta Commerce Manager and connected to your WhatsApp Business Account there. These endpoints use it; they do not edit it.

Commerce settings

Two switches per phone number, read and written live at WhatsApp. phone_id is CallMissed's id for the number, from List numbers.

Read the settings

GET /api/v1/whatsapp/phone_numbers/{phone_id}/commerce_settings · scope whatsapp:read

curl https://api.callmissed.com/api/v1/whatsapp/phone_numbers/9c2b7e30-1d8a-4c5f-9b3d-2f4a6e8b1c2d/commerce_settings \
  -H "Authorization: Bearer cm_your_api_key"
{
  "phone_id": "9c2b7e30-1d8a-4c5f-9b3d-2f4a6e8b1c2d",
  "phone_number_id": "1234567890",
  "is_cart_enabled": true,
  "is_catalog_visible": false
}
FieldTypeNotes
is_cart_enabledboolean, nullableCustomers can add products to a cart and send it as an order
is_catalog_visibleboolean, nullableThe storefront icon shows in the chat header

null means WhatsApp did not report the switch, which is not the same as false. WhatsApp's defaults are cart on and storefront icon hidden.

Update the settings

POST /api/v1/whatsapp/phone_numbers/{phone_id}/commerce_settings · scope whatsapp:write

FieldTypeNotes
is_cart_enabledbooleanOptional
is_catalog_visiblebooleanOptional

Send at least one, otherwise 400. Only the switches you send change.

curl -X POST https://api.callmissed.com/api/v1/whatsapp/phone_numbers/9c2b7e30-1d8a-4c5f-9b3d-2f4a6e8b1c2d/commerce_settings \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "is_catalog_visible": true }'

Returns the settings object, re-read from WhatsApp after the write.

StatusWhen
400Neither switch sent, or no business token on file for the number
403Key is missing whatsapp:read / whatsapp:write
404Phone number not found

Send product messages

Three interactive message types that show catalog products in the chat. All three take whatsapp:send, pick the sending number with phone_id or phone_number_id (one is required, the same as every send), and return the common send response. They are free-form messages, so they need an open 24-hour customer service window, and they are priced and credit-checked like any other send.

product_retailer_id is the product's SKU, shown as Content ID in Commerce Manager.

Send a catalog message

POST /api/v1/whatsapp/messages/catalog · scope whatsapp:send

A bubble with a View catalog button that opens the catalog connected to the sending number.

FieldTypeRequiredNotes
tostring, 5 to 20 charsYesThe customer's number
body_textstring, 1 to 1024 charsYes
footer_textstring, max 60No
thumbnail_product_retailer_idstring, max 256NoThe product whose image becomes the header. Without it WhatsApp uses the first catalog item
context_message_idstring, max 128NoA wamid to quote. The message is sent as a reply to it. Also accepted by the single-product and product-list sends below
curl -X POST https://api.callmissed.com/api/v1/whatsapp/messages/catalog \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "+919000000000",
    "body_text": "Our new single-origin range is in. Tap below to browse.",
    "thumbnail_product_retailer_id": "SKU-114"
  }'

Send a single product

POST /api/v1/whatsapp/messages/product · scope whatsapp:send

FieldTypeRequiredNotes
tostring, 5 to 20 charsYes
catalog_idstring, 1 to 256 charsYesMeta's catalog id
product_retailer_idstring, 1 to 256 charsYes
body_textstring, max 1024No
footer_textstring, max 60No
curl -X POST https://api.callmissed.com/api/v1/whatsapp/messages/product \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "+919000000000",
    "catalog_id": "998877665544",
    "product_retailer_id": "SKU-114",
    "body_text": "The one you asked about."
  }'

Send a product list

POST /api/v1/whatsapp/messages/product_list · scope whatsapp:send

Up to 30 products, grouped in sections.

FieldTypeRequiredNotes
tostring, 5 to 20 charsYes
catalog_idstring, 1 to 256 charsYes
header_textstring, 1 to 60 charsYesText header, required for this type
body_textstring, 1 to 1024 charsYes
footer_textstring, max 60No
sectionsobject[]YesAt least one
sections[].titlestring, max 24When more than one section
sections[].product_itemsobject[]YesAt least one { "product_retailer_id": "..." }. At most 30 products across all sections
curl -X POST https://api.callmissed.com/api/v1/whatsapp/messages/product_list \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "+919000000000",
    "catalog_id": "998877665544",
    "header_text": "Bestsellers",
    "body_text": "Our three most-ordered coffees this month.",
    "sections": [
      { "title": "Beans", "product_items": [ { "product_retailer_id": "SKU-114" }, { "product_retailer_id": "SKU-220" } ] },
      { "title": "Ground", "product_items": [ { "product_retailer_id": "SKU-305" } ] }
    ]
  }'

Send errors

StatusWhen
400Neither phone_id nor phone_number_id sent, more than 30 products, or a missing section title when there is more than one section
402Not enough credits, or a workspace budget cap would be exceeded. Nothing was sent
403Key is missing whatsapp:send
404Phone number not found
409The number is disconnected. Reconnect it
422The body failed validation (a missing required field or an over-long one), or WhatsApp rejected the message, for example because the 24-hour window is closed

Orders

When a customer builds a cart from your WhatsApp catalog and sends it, the order is recorded against your workspace. These endpoints read those orders and their line items.

Orders are created by the customer's action on WhatsApp. There is no create endpoint. Each cart the customer sends becomes one order:

  • It starts with status pending and no reference_id. You set the reference when you first send an order status.
  • It is linked to the customer's contact and conversation, and the cart message also appears in that conversation.
  • subtotal is the sum of each item's quantity times item_price, in the cart's currency. note is the text the customer sent with the cart.
  • A cart that WhatsApp delivers more than once is stored once.
  • A cart whose items use more than one currency, or that is missing a catalog, product, quantity or price, is not stored as an order. The message still appears in the conversation.

Authentication

Authorization: Bearer cm_your_api_key

Reading orders requires wa_commerce:read.

{ "detail": "API key missing required scope: wa_commerce:read. Add it under the key's 'Permissions' section in your dashboard." }

Statuses

pending, processing, partially_shipped, shipped, completed, canceled.

completed and canceled are terminal.

The order object

{
  "id": "o1a2…",
  "tenant_id": "a0b1…",
  "conversation_id": "c0ff…",
  "contact_id": "4411…",
  "wa_message_id": "wamid.HBg…",
  "catalog_id": "998877665544",
  "reference_id": "ORD-4471",
  "status": "pending",
  "currency": "INR",
  "subtotal": 2499.0,
  "note": "Please deliver after 6pm",
  "created_at": "2026-08-17T07:20:00Z",
  "updated_at": "2026-08-17T07:20:00Z"
}
FieldTypeNotes
wa_message_idstringThe WhatsApp message that carried the cart
reference_idstring | nullYour own bill reference, once one has been attached
subtotalnumberSum of the line items, in currency
notestring | nullFree-text the customer typed with the order

GET/api/v1/commerce/orders

Newest first.

ParameterTypeRequiredConstraints
statusstringNoOne of the six statuses
contact_idUUIDNoOne customer's orders
created_fromdatetimeNoInclusive lower bound on created_at
created_todatetimeNoInclusive upper bound on created_at
limitintegerNo1 <= limit <= 200, default 50
offsetintegerNo0 <= offset <= 100000, default 0
curl "https://api.callmissed.com/api/v1/commerce/orders?status=pending&limit=50" \
  -H "Authorization: Bearer cm_your_api_key"

An unknown status returns 422 status must be one of: pending, processing, partially_shipped, shipped, completed, canceled.

GET/api/v1/commerce/orders/{order_id}

The order plus its line items, oldest first.

{
  "id": "o1a2…",
  "status": "pending",
  "currency": "INR",
  "subtotal": 2499.0,
  "items": [
    {
      "id": "i9b8…",
      "product_retailer_id": "SKU-114",
      "quantity": 2,
      "item_price": 999.0,
      "currency": "INR",
      "created_at": "2026-08-17T07:20:00Z"
    },
    {
      "id": "i7c6…",
      "product_retailer_id": "SKU-220",
      "quantity": 1,
      "item_price": 501.0,
      "currency": "INR",
      "created_at": "2026-08-17T07:20:00Z"
    }
  ]
}

product_retailer_id is your own SKU as it appears in the catalog — join on it to look the product up in your system.

404 Order not found for an unknown id or another tenant's order.

Orders errors

StatusWhen
403Key is missing wa_commerce:read
404Order not found
422Unknown status value

Reading orders does not consume credits.

On this page