Mapping WhatsApp template variables to Shopify order fields
How variable mapping on a WhatsApp automation works: which Shopify fields each trigger offers, header and button placeholders, and why empty ones fail.
A WhatsApp template is a sentence with holes in it. Hi {{1}}, your order {{2}} for {{3}} is confirmed. Meta approves the sentence; your store has to fill the holes, for every order, with the right value in the right hole. In Beacon Messenger that filling is set up once per automation, on a page that lists every hole the template has and asks which Shopify field goes in it. This post walks that page from top to bottom: where the holes come from, what you can put in each one, what the preview shows, and what happens if you leave one empty.
Where the variables come from
Open Automations, press Set up or Edit on a card, and the first control is the template picker. It lists only templates Meta has approved, each shown as name, language and category, and the key behind the choice is the name plus the language, because the same template name can exist in several languages with different placeholder counts. Pick one and the app reads the template's components and extracts every placeholder it finds, in three places:
- **Body.** The main text. Placeholders are either positional, {{1}} {{2}} {{3}}, or named, {{customer_name}} {{order_id}}, depending on how the template was created in WhatsApp Manager.
- **Header.** Only text headers can carry a variable, and Meta allows one. An image or document header has nothing to map.
- **URL buttons.** A button whose link ends in {{1}} is a dynamic URL. The variable is the suffix appended to the fixed part of the link. The mapping page labels it with the button text, for example URL button "Track order" suffix, so you know which button you are filling.
Each placeholder becomes one select on the page, in the order Meta lists them. Changing to a different template clears every mapping, because {{2}} in one template has nothing to do with {{2}} in another.
What each select offers
Every select starts at Leave empty and then lists merge fields, which are the Shopify values the app knows how to produce for that trigger. The list is filtered per automation, so you are never offered a tracking number on an order confirmation or a checkout link on a shipping update.
| Merge field | Order confirmation and COD | Shipping update | Abandoned checkout |
|---|---|---|---|
| Customer first name, full name, shop name | yes | yes | yes |
| Order name (#1001), order number (1001) | yes | yes | no |
| Order total with currency, payment method | yes | yes | no |
| Items summary (first 3), item count, first item title | yes | yes | item count and first item only |
| Order status page URL, and its path for URL buttons | yes | yes | no |
| Tracking number, carrier, tracking URL | no | yes | no |
| Checkout total, checkout URL, and its path for URL buttons | no | no | yes |
Two fields exist in pairs and the pairing matters. Order status page URL is the full https address, meant for the body of a message. Order status URL path is the same address with the store domain removed, meant for a URL button whose fixed part is already your domain. Put the full URL in a button suffix and the customer gets your domain twice in one link. The track order button post goes through that setup end to end; the checkout URL and path pair works the same way for abandoned checkout recovery links.
Named and positional placeholders
Meta's newer templates can use named placeholders, so the template reads {{customer_name}} instead of {{1}}. Beacon Messenger treats both the same on the mapping page: a named placeholder is still a hole to fill, and the name is just a label. Mapping {{customer_name}} to Customer first name is allowed, and so is mapping it to Shop name if that is what you want. The name in the template does not auto-select a field, because the names merchants type in WhatsApp Manager rarely match any system exactly.
The difference shows only at send time. For a named placeholder the app sends Meta the value together with the parameter name; for a positional one it sends the values in order. You never see that, but it is why a template edited from positional to named in WhatsApp Manager has to be re-selected in the app: the holes have changed identity.
The preview with sample data
Under the selects the page renders the template body with a fixed set of sample values: Ana, Ana García, Acme Store, order #1042, $84.00 USD, Cash on Delivery, 2× Ceramic Mug, 1× Linen Tee, a UPS tracking number, and so on. Pick a field and the hole fills immediately. The preview is for the body only; header and button variables are not drawn, but the same values would be used.
Read the preview as a customer would. Hi Ana, your order 1042 is ready reads oddly without the hash; that is Order number where you meant Order name. Hi Ana García, thanks for your order! may be more formal than your brand; swap to the first name. The sample total includes the currency code, which is what real sends include too, so if the template already says USD after the placeholder you will see USD twice and can fix the template before anyone else does.
What unmapped means
If any placeholder is still at Leave empty, a warning appears under the selects: 2 variables are unmapped and will be sent empty. Meta rejects templates with empty variables. The app lets you save anyway, because you might be mid-setup, but it is telling you plainly that the automation will not deliver.
The mechanics: when a message is built, every placeholder gets a parameter, and an unmapped one gets an empty string. Meta validates the parameters against the approved template and refuses a message with an empty text parameter. The attempt then shows in the message log as failed with Meta's error, rather than as skipped, because the app did try. If the field you mapped produces nothing for a particular order, say Payment method on an order with no gateway name, the merge field fallbacks step in with a neutral value so the message still goes.
What stops a save
- Turning the automation On with no template chosen: Choose a template before turning the automation on.
- A template that was approved when you opened the page and is not any more, or whose language was changed: That template is no longer approved. Refresh templates and pick another.
- A mapping to a field that does not belong to this trigger, which can only happen with a stale form: the error names the field and the automation.
Everything else saves. Delay, consent and the other rules on the same page are covered in the automation checklist; this post stays on the variables.
A mapping that works for most stores
- Order confirmation body: {{1}} Customer first name, {{2}} Order name, {{3}} Order total with currency. If the template has a fourth hole, Items summary.
- Order confirmation URL button: Order status URL path, with the button's fixed part set in WhatsApp Manager to your store domain followed by a slash.
- Shipping update body: {{1}} Customer first name, {{2}} Order name, {{3}} Carrier. URL button: Tracking URL is a full address, so it belongs in the body; for a button, Meta needs a suffix on a fixed carrier domain, which varies by carrier, so most stores put the tracking link in the body and the order status path on the button.
- Abandoned checkout body: {{1}} Customer first name, {{2}} First item title or Checkout total. URL button: Checkout URL path.
- Save, send yourself a test from the Connection page, and read the message on a phone. The preview is good; the phone is better.
The variable mapping is the one part of WhatsApp notifications that cannot be automated away, because only you know what your template says. Once it is set, it stays set for every order, and Beacon Messenger only asks you to revisit it when you change the template.
Frequently asked questions
Why is the merge field I want not in the list?
The list is filtered to the automation you are editing. Tracking fields exist only on Shipping update, checkout fields only on Abandoned checkout, and order fields are not offered on Abandoned checkout because there is no order yet. If the field is missing on the right automation, refresh the page; the list is built from the trigger, not from the template.
Can I put plain text in a variable, such as my store's phone number?
Not from the mapping page; every hole takes a Shopify field. Fixed text belongs in the template itself. If you need the shop name, that is a merge field, and it is the one constant value the list does offer.
I changed the template in WhatsApp Manager and the message stopped sending. Why?
Editing a template sends it back to Meta for review, and until it is approved again the app treats it as not approved and skips. Once approved, open the automation, press Refresh templates, re-select it and check the mapping, because added or renamed placeholders arrive unmapped.
Does leaving a variable empty save money by not sending?
No. The message is attempted and rejected by Meta, so it costs nothing, but it also tells the customer nothing. Map the variable or pick a template with fewer holes.
More guides
- WhatsApp Business app drops order tools: move orders to Shopify
- A customer replied STOP to a WhatsApp order message. Now what?
- WhatsApp marketing templates leave the Cloud API in October 2027
- WABA to Messaging Account: what changes for Shopify WhatsApp
- Order paid later, refunded or edited: which WhatsApp messages send
- Edited your WhatsApp automation? What queued messages send
- How to add a WhatsApp chat button to your Shopify store (2026)
- How to send Shopify order confirmations and shipping updates over WhatsApp with the official Cloud API
- Cash on delivery on Shopify: confirm orders over WhatsApp before you ship
- Recovering abandoned checkouts on Shopify with WhatsApp, the compliant way
- Why WhatsApp apps get your number banned: linked device vs API
- How a "free" WhatsApp app for Shopify ends up charging you
- Por qué una app de WhatsApp "gratis" para Shopify te cobra
- Pushdaddy or SuperLemon alternative: WhatsApp apps compared
- How to verify Shopify WhatsApp notifications were delivered
- Chat button still on your store after uninstalling the app?
- WhatsApp API pricing changes on Oct 1, 2026: Shopify impact
- Setting up the WhatsApp Cloud API with Meta's MCP and an AI agent
- WhatsApp chat outside business hours: what shoppers should see
- WhatsApp product sharing on Shopify: tracking dark social
- WhatsApp template rejected? Fixing Shopify order templates
- One WhatsApp number or two? Shopify notifications & support
- Shopify Canvas and Beacon Messenger: what works today
- Shopify now collects WhatsApp marketing consent at checkout. Here is what it changes
- Split shipments on Shopify: how many WhatsApp updates to send
- WhatsApp's 250-a-day messaging limit and your Shopify store
- WhatsApp, SMS or email for Shopify order notifications?
- WhatsApp is down: what happens to your Shopify order notifications
- Shopify orders with no phone number: why WhatsApp messages get skipped
- Shopify rollout discounts and WhatsApp order messages
- Add a Track order button to WhatsApp order messages
- Which Shopify orders trigger a WhatsApp message?
- The abandoned checkout timer restarts every time the shopper comes back
- Blank names, twelve-item orders: what WhatsApp merge fields fall back to
- Who looked at your customers' phone numbers? The access log behind a WhatsApp app
- Send a WhatsApp test message before your first order: what the Connect and Test buttons check
- Disconnect, update credentials, app secret: what each does
- COD reply not tagged: how Beacon Messenger matches replies
- WhatsApp template language: why name alone is not enough
- Finding one WhatsApp message in the Beacon Messenger log
- WhatsApp automation is On but nothing sends: a checklist
- Every WhatsApp chat button setting in the Shopify theme editor
- WhatsApp template examples for Shopify: order, shipping, COD, cart
- The Share on WhatsApp block, setting by setting
- WhatsApp order messages when customers speak several languages
- Reading the Beacon Messenger dashboard: sent, delivered, failed, skipped
- Shopify batch fulfilment: what happens to 250 WhatsApp shipping messages
- WhatsApp template status: approved, pending, paused, disabled, and what sends
- WhatsApp quality rating: the field on the Connected number card
- COD returns (RTO) on Shopify: confirm orders on WhatsApp first
- WhatsApp error codes on failed messages: a reference
- WhatsApp display name: what customers see on your order messages
- Shopify Messaging WhatsApp automations vs Beacon Messenger
- OXXO, bank transfer and pay-later orders: when the WhatsApp confirmation goes out
- How many WhatsApp messages will Black Friday send? Sizing your plan
- WhatsApp usernames and BSUIDs: what changes for Shopify order messages
- Reconciling your WhatsApp bill with the Beacon Messenger log
- Track with Shop vs WhatsApp shipping updates on Shopify
- Meta changed my WhatsApp template from utility to marketing
- Shopify's new app security review: what Beacon Messenger can access
- A shopper cancels their own Shopify order: what WhatsApp sends
- Customer erasure in 5 days: what the WhatsApp log keeps
- WhatsApp INR billing deadline: Indian Shopify stores
- WhatsApp template headers: text, image or document?
- Gift orders on WhatsApp: buyer's phone or the recipient's?
- WhatsApp order messages at night: when each one sends
- Downgrading a WhatsApp app plan after peak season: what changes
- Shopify subscription renewals and WhatsApp order messages