API reference
Event catalog
All 18 events with their exact variables, types and examples.
Eighteen events. There are no others. Map any other store state, packed, delayed, on hold, onto order_status and put your own wording in orderStatus.
Each event's variables are listed in positional order: the first is {{1}}, the second {{2}}, and so on. You never send positions, you send { variableName: value } to POST /v1/notifications/send and the mapping is done for you. The order matters only when you are reading the template body below and matching a placeholder to a name.
The Body shown for each event is the exact approved template text. *text* renders as bold in WhatsApp. Newlines and tabs in your values are collapsed to a single space before sending, because Meta rejects parameters containing them with error 132000.
Under each event's variables is that template rendered with the approved example values, as it arrives on the customer's phone.
Jump to an event
- otp_verification
- password_reset
- order_verification
- welcome
- order_confirmation
- order_status
- order_cancelled
- order_shipped
- out_for_delivery
- order_delivered
- payment_received
- invoice
- refund_processed
- return_requested
- return_approved
- cart_recovery
- review_request
- back_in_stock
Summary
| Event | Category | Template name | Variables, in positional order |
|---|---|---|---|
otp_verification | AUTHENTICATION | otp_verification | otp |
password_reset | AUTHENTICATION | password_reset | otp |
order_verification | AUTHENTICATION | order_verification | otp |
welcome | UTILITY | welcome | customerName, storeName |
order_confirmation | UTILITY | order_confirmation | customerName, orderId, orderTotal, trackingLink |
order_status | UTILITY | order_status_update | orderId, orderStatus, trackingLink |
order_cancelled | UTILITY | order_cancelled | orderId, reason |
order_shipped | UTILITY | order_shipped | orderId, awbCode, trackingLink |
out_for_delivery | UTILITY | out_for_delivery | orderId, trackingLink |
order_delivered | UTILITY | order_delivered | orderId, reviewLink |
payment_received | UTILITY | payment_received | orderId, amount |
invoice | UTILITY | invoice | customerName, orderId, invoiceNumber, amount, invoiceLink |
refund_processed | UTILITY | refund_processed | orderId, amount |
return_requested | UTILITY | return_requested | orderId |
return_approved | UTILITY | return_approved | orderId |
cart_recovery | MARKETING | cart_recovery | customerName, cartRecoveryLink, discountCode |
review_request | MARKETING | review_request | customerName, productName, reviewLink |
back_in_stock | MARKETING | back_in_stock | productName, productLink |
order_status is the one event whose template name differs from its key. You still send "event": "order_status".
Authentication and account events
The three passcode events are AUTHENTICATION category, carry an automatic Copy code button and a 10-minute expiry footer, and take exactly one variable. You pass only { "otp": "123456" }, the platform supplies the code to both the body and the button, which Meta requires and which is the usual cause of a component-mismatch rejection when hand-built.
Meta owns the wording of an authentication template: the submitted component asks for the security recommendation, the expiry footer and the button, so the delivered message can carry an extra line of Meta's own security copy beneath the body shown here.
otp_verification
One-time passcode for login or phone verification. Category AUTHENTICATION.
{{1}} is your verification code.| Field | Required | Type | Description |
|---|---|---|---|
| otp | Yes | string | The one-time passcode. Example: 123456 |
123456 is your verification code.
12:04otp_verification message, shown with its approved example values.password_reset
One-time passcode for resetting an account password. Category AUTHENTICATION.
{{1}} is your password reset code.| Field | Required | Type | Description |
|---|---|---|---|
| otp | Yes | string | The password-reset passcode. Example: 123456 |
123456 is your verification code.
12:04password_reset message, shown with its approved example values.order_verification
Passcode confirming a Cash-on-Delivery order before it is accepted. Category AUTHENTICATION.
{{1}} is your order confirmation code.| Field | Required | Type | Description |
|---|---|---|---|
| otp | Yes | string | The COD confirmation passcode. Example: 123456 |
123456 is your verification code.
12:04order_verification message, shown with its approved example values.welcome
Sent once when a customer creates an account. Category UTILITY, but reported under group: "Authentication" in the catalog.
Welcome to {{2}}, {{1}}! 👋 Your account is ready and you can now track orders, save addresses and check out faster. Happy shopping!| Field | Required | Type | Description |
|---|---|---|---|
| customerName | Yes | string | Customer name, {{1}}.Example: Alex |
| storeName | Yes | string | Store name, {{2}}.Example: Homeomead |
The body reads {{2}} before {{1}}. That changes nothing about what you send: always pass variables by name.
Welcome to Homeomead, Alex! 👋 Your account is ready and you can now track orders, save addresses and check out faster. Happy shopping!
12:04welcome message, shown with its approved example values.Order events
order_confirmation
Sent immediately after a customer places an order. Category UTILITY.
Hi {{1}}, your order *{{2}}* is confirmed! ✅
Order total: Rs.{{3}}
Track your order here: {{4}}
We'll message you as soon as it ships. Thank you for shopping with us!| Field | Required | Type | Description |
|---|---|---|---|
| customerName | Yes | string | Customer name. Example: Alex |
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
| orderTotal | Yes | string | Order total, formatted. The template already prints Rs., do not include a currency symbol.Example: 1,499.00 |
| trackingLink | Yes | string (URL) | Link where the customer can track the order. Example: https://example.com/track/ORD-12345 |
Hi Alex, your order #ORD-12345 is confirmed! ✅
Order total: Rs.1,499.00
Track your order here: https://example.com/track/ORD-12345
We'll message you as soon as it ships. Thank you for shopping with us!
order_confirmation message, shown with its approved example values.order_status
Sent whenever an order's status changes. Category UTILITY. The Meta template is named order_status_update, the only event where the two differ, but you still send "event": "order_status".
📦 Update on your order *{{1}}*: the status is now *{{2}}*.
Track it here: {{3}}
Thanks for your patience!| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
| orderStatus | Yes | string | The new status, worded as you want the customer to read it. This is where every store state that has no event of its own goes. Example: Packed |
| trackingLink | Yes | string (URL) | Order tracking link. Example: https://example.com/track/ORD-12345 |
📦 Update on your order #ORD-12345: the status is now Packed.
Track it here: https://example.com/track/ORD-12345
Thanks for your patience!
order_status message, shown with its approved example values.order_cancelled
Sent when an order is cancelled. Category UTILITY.
Your order *{{1}}* has been cancelled. Reason: {{2}}.
Any payment already made will be refunded as per our refund policy. Contact us if you need help.| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
| reason | Yes | string | Cancellation reason. The template adds the full stop. Example: Requested by customer |
Your order #ORD-12345 has been cancelled. Reason: Requested by customer.
Any payment already made will be refunded as per our refund policy. Contact us if you need help.
order_cancelled message, shown with its approved example values.Shipping events
order_shipped
Sent when an order is dispatched with a tracking or AWB code. Category UTILITY.
🚚 Good news, your order *{{1}}* has shipped!
Tracking number: {{2}}
Track your shipment: {{3}}
It is on its way to you.| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
| awbCode | Yes | string | Carrier AWB / tracking number. Example: AWB123456789 |
| trackingLink | Yes | string (URL) | Carrier tracking link. Example: https://example.com/track/AWB123456789 |
🚚 Good news, your order #ORD-12345 has shipped!
Tracking number: AWB123456789
Track your shipment: https://example.com/track/AWB123456789
It is on its way to you.
order_shipped message, shown with its approved example values.out_for_delivery
Sent when the shipment is out for delivery. Category UTILITY.
🛵 Your order *{{1}}* is out for delivery and should arrive today.
Track it live: {{2}}
Please keep your phone reachable.| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
| trackingLink | Yes | string (URL) | Tracking link. Example: https://example.com/track/ORD-12345 |
🛵 Your order #ORD-12345 is out for delivery and should arrive today.
Track it live: https://example.com/track/ORD-12345
Please keep your phone reachable.
out_for_delivery message, shown with its approved example values.order_delivered
Sent when an order is marked delivered. Category UTILITY.
🎉 Your order *{{1}}* has been delivered. We hope you love it!
Tell us how we did: {{2}}
Thank you for shopping with us.| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
| reviewLink | Yes | string (URL) | Leave-a-review link. Example: https://example.com/review/ORD-12345 |
🎉 Your order #ORD-12345 has been delivered. We hope you love it!
Tell us how we did: https://example.com/review/ORD-12345
Thank you for shopping with us.
order_delivered message, shown with its approved example values.Payment and return events
payment_received
Sent when a payment is confirmed for an order. Category UTILITY.
💳 We've received your payment of Rs.{{2}} for order *{{1}}*.
Your order is now confirmed and being processed. Thank you!| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id, {{1}}.Example: #ORD-12345 |
| amount | Yes | string | Amount paid, formatted, {{2}}. Rs. is already in the template.Example: 1,499.00 |
💳 We've received your payment of Rs.1,499.00 for order #ORD-12345.
Your order is now confirmed and being processed. Thank you!
payment_received message, shown with its approved example values.invoice
Sent when the tax invoice for an order is issued. Category UTILITY.
🧾 Hi {{1}}, the invoice for your order *{{2}}* is ready.
Invoice number: {{3}}
Amount: Rs.{{4}}
Download it here: {{5}}
Keep it for your records.| Field | Required | Type | Description |
|---|---|---|---|
| customerName | Yes | string | Customer name. Example: Alex |
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
| invoiceNumber | Yes | string | Invoice number. Example: INV-2024-0001 |
| amount | Yes | string | Invoice total, formatted. Rs. is already in the template.Example: 1,499.00 |
| invoiceLink | Yes | string (URL) | Link to download the invoice. Example: https://example.com/invoice/INV-2024-0001 |
🧾 Hi Alex, the invoice for your order #ORD-12345 is ready.
Invoice number: INV-2024-0001
Amount: Rs.1,499.00
Download it here: https://example.com/invoice/INV-2024-0001
Keep it for your records.
invoice message, shown with its approved example values.refund_processed
Sent when a refund is issued. Category UTILITY.
💰 A refund of Rs.{{2}} for your order *{{1}}* has been processed.
Please allow 5-7 business days for it to reflect in your account.| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id, {{1}}.Example: #ORD-12345 |
| amount | Yes | string | Refund amount, formatted, {{2}}.Example: 1,499.00 |
💰 A refund of Rs.1,499.00 for your order #ORD-12345 has been processed.
Please allow 5-7 business days for it to reflect in your account.
refund_processed message, shown with its approved example values.return_requested
Sent when a customer requests a return. Category UTILITY.
↩️ We've received your return request for order *{{1}}*.
Our team is reviewing it and will update you shortly with the next steps.| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
↩️ We've received your return request for order #ORD-12345.
Our team is reviewing it and will update you shortly with the next steps.
return_requested message, shown with its approved example values.return_approved
Sent when a return request is approved. Category UTILITY.
✅ Your return for order *{{1}}* has been approved.
Pickup details and next steps will follow shortly. Thank you for your patience.| Field | Required | Type | Description |
|---|---|---|---|
| orderId | Yes | string | Human-readable order id. Example: #ORD-12345 |
✅ Your return for order #ORD-12345 has been approved.
Pickup details and next steps will follow shortly. Thank you for your patience.
return_approved message, shown with its approved example values.Marketing events
All three are MARKETING category. They cost several times what a utility message costs, require explicit opt-in in most jurisdictions, and carry an automatic Reply STOP to unsubscribe footer.
cart_recovery
Nudges a customer back to an abandoned cart. Category MARKETING.
🛒 Hi {{1}}, you left some items in your cart!
Finish your order here: {{2}}
Use code {{3}} for a discount at checkout.
Your cart is saved for a limited time.| Field | Required | Type | Description |
|---|---|---|---|
| customerName | Yes | string | Customer name. Example: Alex |
| cartRecoveryLink | Yes | string (URL) | Direct link back to the saved cart. Example: https://example.com/cart/abc123 |
| discountCode | Yes | string | Incentive code. The template always prints the “Use code” line, so send a dash ( -) if you have no code rather than leaving it blank.Example: SAVE10 |
🛒 Hi Alex, you left some items in your cart!
Finish your order here: https://example.com/cart/abc123
Use code SAVE10 for a discount at checkout.
Your cart is saved for a limited time.
Reply STOP to unsubscribe
12:04cart_recovery message, shown with its approved example values.review_request
Asks a customer to review a delivered product. Category MARKETING.
⭐ Hi {{1}}, how are you finding your *{{2}}*?
Share a quick review here: {{3}}
It takes a minute and helps other shoppers a lot.| Field | Required | Type | Description |
|---|---|---|---|
| customerName | Yes | string | Customer name. Example: Alex |
| productName | Yes | string | Product name. Example: Arnica Montana 30CH |
| reviewLink | Yes | string (URL) | Link to leave a review. Example: https://example.com/review/123 |
⭐ Hi Alex, how are you finding your Arnica Montana 30CH?
Share a quick review here: https://example.com/review/123
It takes a minute and helps other shoppers a lot.
Reply STOP to unsubscribe
12:04review_request message, shown with its approved example values.back_in_stock
Alerts a customer that a wishlisted product is available again. Category MARKETING.
🔔 Good news, *{{1}}* is back in stock!
Grab it here before it sells out again: {{2}}
You're receiving this because you asked to be notified.| Field | Required | Type | Description |
|---|---|---|---|
| productName | Yes | string | Product name. Example: Arnica Montana 30CH |
| productLink | Yes | string (URL) | Product page link. Example: https://example.com/product/arnica-30ch |
🔔 Good news, Arnica Montana 30CH is back in stock!
Grab it here before it sells out again: https://example.com/product/arnica-30ch
You're receiving this because you asked to be notified.
Reply STOP to unsubscribe
12:04back_in_stock message, shown with its approved example values.Reading the catalog at runtime
Everything on this page is served by GET /v1/notifications/catalog, including the template bodies and the variable descriptions. Read it at build time rather than hard-coding variable names, and a store's field mapping cannot drift from the templates it actually sends.
const res = await fetch("https://whatsapp-api.growcord.in/api/v1/notifications/catalog", {
headers: { Authorization: `Bearer ${process.env.WA_API_KEY}` },
});
const catalog = await res.json();
const shipped = catalog.find((e) => e.event === "order_shipped");
"/docs/api/notifications"
console.log(shipped.variables);