A WhatsApp catalogue API workflow needs stable product identifiers, a connected catalogue and an order-event handler that turns a customer’s submitted cart into the right internal record. Sending a product message is not proof of payment, reserved stock or completed fulfilment. Keep those decisions in the business’s order process.
Twilio’s official catalogue documentation provides a concrete supported route through its content templates. It explains catalogue creation, Content IDs, template use and receiving cart webhooks. This guide is scoped to that documented route; it does not claim every Meta API version or provider uses identical field names or supports identical commerce features. Twilio catalogue documentation.
What must be connected before sending products?
Identify the business account, catalogue and product records. Twilio’s setup guide directs the operator through Commerce Manager and warns not to edit the catalogue owner during that process. Ownership should be established intentionally, not changed casually to make a demonstration work.
The guide describes several ways to add items, including manual entry, data feeds and partner platform connections. Choose the route that fits the source catalogue and establish who updates it. Uploading products once is not the same as maintaining an accurate catalogue when availability or descriptions change.
Twilio says the same catalogue cannot be used by multiple WhatsApp Business Accounts in the documented connection route. Check the account arrangement before designing a multi-brand catalogue structure. Do not assume that copying a catalogue name creates a supported shared ownership model.
How do product identifiers map between systems?
Twilio explains that Meta’s interface calls the item identifier Content ID, while developer documentation refers to Item ID or Product Retailer ID. Its webhook exposes Product Retailer ID. These names should be mapped explicitly to the business’s own product identifier.
The guide says Content IDs must be unique within the catalogue. Do not use a display title as the sole key. Titles can change, and similar products or variants can share much of their wording while needing different order and stock records.
Create an identity map before synchronisation. Include the internal SKU or variant reference, catalogue identifier and the exact identifier used in messages and inbound events. Where a variant is not represented clearly, resolve it before accepting customer carts. An order line that staff must interpret from a product name is an unresolved integration requirement.
Which catalogue message should you use?
| Presentation | Documented Twilio behaviour | Acceptance question |
|---|---|---|
| Single product | Opens the selected item; single-product presentation is in-session | Does it identify the intended item and variant? |
| Multi-product | Presents a selection of catalogue items | Do item IDs match the intended selection? |
| Full catalogue | Opens the connected catalogue when enabled for the sender | Is the visible catalogue the current one? |
| Out-of-session template | Requires the applicable approval route | Is the actual template approved for its use? |
The documentation distinguishes in-session single-product messages from an approved multi-product template containing one item outside the session. Do not collapse those into a claim that every product presentation is allowed in every conversation state.
These distinctions affect the customer experience and the content configuration. Test the exact presentation you intend to send rather than assuming a successful sample template proves the full catalogue workflow.
What does a submitted cart event contain?
Twilio documents different webhook responses for a product enquiry and a customer submitting an order. The order data includes the catalogue identity and product items with their product references and quantities. A question about an item should not be mistaken for an order merely because it contains product context.
On receipt, the application should identify the event, map the products and create or locate the relevant internal request. Then it must apply the business’s own rules for availability, payment and fulfilment. The opened page does not establish that receiving a cart automatically reserves inventory or collects money.
Preserve the original event reference and the resulting internal record link. If an item is unknown or no longer offered, keep the case visible for resolution rather than dropping the line silently. These are proposed integration controls, not assertions that a provider implements your stock policy automatically.
An original catalogue identity and event record
Use this artefact during implementation:
Catalogue identity: account owner, catalogue ID and authoritative product source.
Product identity: internal SKU/variant, Content ID and customer-facing description.
Update ownership: system or role allowed to change description, availability and other catalogue fields.
Incoming event: event type, provider reference and received product identifiers.
Mapping result: matched internal items, unknown items and unresolved variant differences.
Order result: internal enquiry or order reference and the state actually created.
Commercial checks: stock decision, payment decision and fulfilment owner, recorded separately.
Exception result: customer wording, operator task and evidence of resolution.
The record is original editorial guidance. It should be adapted to the chosen provider’s current payload and retained with restricted access where customer information is present. It is not a universal API schema.
How should synchronisation failures be tested?
Change a test product’s availability in the source system and observe when the catalogue reflects the intended state. Record the actual update route and result. Do not invent a universal refresh interval or claim instant synchronisation from a successful manual upload.
Next, submit a test cart containing an item whose internal mapping is deliberately absent. Confirm that staff can identify the missing mapping and that the customer is not told the order is fully accepted if the application has only recorded an unresolved request.
Also test a repeated event through the provider’s supported test mechanism. The integration should not create duplicate fulfilment actions merely because the same event is processed again. Record the mechanism used to recognise an existing internal request and the actual outcome.
Finally, ask a product question without submitting a cart. Inspect whether it is routed as an enquiry. This guards the boundary between product context and an actual order event, which the Twilio documentation explicitly distinguishes.
What should be ready before customers use the catalogue?
Confirm account ownership, current product data, template requirements and the staff process for unknown or unavailable items. Establish the route for payment and delivery confirmation separately. A catalogue message can help a customer choose products while leaving several business decisions outstanding.
Discuss the workflow through Spout’s WhatsApp Business service or start an enquiry with the identity map and intended order process.
By Spout Team. Prepared with AI-assisted drafting using the linked primary documentation.