WhatsApp Marketing Messages API 2026: optimization_spec Fix

In the WhatsApp Marketing Messages API, optimization_spec is the object on a marketing template that sets a max price: a bid_amount per 1,000 deliveries in your account's smallest currency unit (paise in India) plus bid_strategy: "LOWEST_COST_WITH_BID_CAP". Meta introduced it on 18 June 2026 as the replacement for bid_spec, kept the two inner fields identical, and stopped supporting bid_spec on templates after 31 July 2026. If your template create or update calls still send bid_spec, rename the wrapper object and keep the values. This guide shows the exact payloads, the paise maths at India's ₹0.8631 marketing rate, the errors you will hit, and the bigger October 2027 deadline sitting behind all of it.

Every field, date and error code below comes from Meta's Marketing Messages API changelog and pricing reference, read on 27 October 2026. Max price is still a beta feature that Meta is changing month by month, so check the live reference before you ship code against it.

What changed in the Marketing Messages API in 2026

The Marketing Messages API (MM API) is the product Meta used to call MM Lite. It went generally available under the new name on 19 November 2025. It sends marketing templates through a separate /marketing_messages endpoint that has, in Meta's words, "a similar technical schema" to Cloud API, and adds delivery optimisation, time-to-live on messages and richer reporting. If you are new to the product, start with our WhatsApp MM Lite API explainer, then come back for the 2026 payload changes.

The 2026 changelog is dense. These are the entries that change code or cost for an Indian sender:

Meta's own timeline puts general availability of max price in Q2 2027, so treat every field below as beta.

bid_spec vs optimization_spec: field by field

The rename is smaller than it looks. Only the wrapper object on the template changed. The table maps what moved and what did not:

That last row trips people up. The rename covers the template. On the send call, Meta's pricing reference still wraps the per-message multiplier in an object called bid_spec and notes the multiplier "is subject to change" during beta. So a blanket find-and-replace of bid_spec across your codebase can break your send call. Change template payloads, then test the send path on its own.

The payloads: create, update and revert a max price template

Create a marketing template with a max price by adding optimization_spec to the normal Message Templates API call. The values here cap the price at ₹0.87 per delivered message:

POST /v24.0/<WABA_ID>/message_templates
{
  "name": "festive_sale_oct",
  "language": "en",
  "category": "MARKETING",
  "components": [ ... your header, body and buttons ... ],
  "optimization_spec": {
    "bid_amount": 87000,
    "bid_strategy": "LOWEST_COST_WITH_BID_CAP"
  }
}

To change the price on an existing template, post to the template ID with both fields. Meta says an update can take up to one hour to propagate, so do not change price minutes before a campaign:

POST /v24.0/<TEMPLATE_ID>/
{
  "optimization_spec": {
    "bid_amount": 95000,
    "bid_strategy": "LOWEST_COST_WITH_BID_CAP"
  }
}

To put a template back on rate card pricing, send both fields as null and nothing else. That also clears any country overrides:

POST /v24.0/<TEMPLATE_ID>/
{
  "optimization_spec": { "bid_amount": null, "bid_strategy": null }
}

Leaving optimization_spec out of an update keeps the template's current pricing mode. Since 17 July 2026 you can also pass source_template_id to duplicate an approved template with a new max price, and the copy is created already approved, which saves a fresh review for every price test.

Country overrides

If one template goes to several countries, bid_country_multiplier_overrides scales the base bid per country, keyed by ISO country code. Unlisted countries use 1.0, and the effective bid is bid_amount × multiplier:

"optimization_spec": {
  "bid_amount": 87000,
  "bid_strategy": "LOWEST_COST_WITH_BID_CAP",
  "bid_country_multiplier_overrides": { "IN": 1.2, "AE": 0.9 }
}

Two quirks. On update, omitting the map keeps it, an empty {} clears it, and a non-empty map replaces it entirely, so always send the full list. When you read the template back, Meta returns the overrides as a list of {"key": ..., "value": ...} objects, not a map, so your parser needs to handle both shapes. If you build these calls in JavaScript, our WhatsApp API Node.js guide covers retries and idempotency for the same Graph endpoints.

The paise maths for India

bid_amount is the most you will pay per 1,000 deliveries, written in the smallest unit of your account currency. For an INR account that is paise. Meta's own example: ₹0.87 per message is 87 paise × 1,000 = 87000. You are then charged the max price or less for each delivery, and the bid cap works alongside any daily or lifetime budget you set.

India's published marketing rate card is ₹0.8631 per message at the time of writing. That gives these reference points:

The 1.2× row is not our invention. Meta's recommended four-arm A/B test, with 10,000 send requests per arm, sets one arm at 1.5× rate card, or 1.2× for India and Saudi Arabia. Since September 2026 Meta's advice is to set bid_amount at the highest price you will accept and use a per_message_bid_multiplier below 1 to pull individual sends down, not to push them up.

A max price is a ceiling, not a discount. It decides how aggressively Meta delivers your message against competing marketing traffic. A higher cap can win more deliveries to engaged users, and a cap below what the auction needs can mean fewer deliveries. Meta's reach estimate (GET /<WABA_ID>/reachestimate with a country and a 1, 7, 14 or 28-day window) gives a delivery range and a cost range, and Meta is explicit that these "do not guarantee" outcomes. In analytics and webhooks this traffic appears as MARKETING_LITE_DYNAMIC (lowercase in webhooks). Delivered and read webhooks carry an estimated cost, but your invoice is the final number.

The send call and per-message multiplier

A max price template only works on the Marketing Messages endpoint, POST /v24.0/<PHONE_NUMBER_ID>/marketing_messages. The body looks like a normal template send, plus the optional multiplier object Meta documents at the top level:

POST /v24.0/<PHONE_NUMBER_ID>/marketing_messages
{
  "messaging_product": "whatsapp",
  "to": "91XXXXXXXXXX",
  "type": "template",
  "template": { "name": "festive_sale_oct", "language": { "code": "en" } },
  "bid_spec": { "per_message_bid_multiplier": 0.8 }
}

The multiplier must be positive and defaults to 1. Meta's example shows it as a quoted string while the parameter table lists it as a float, so send a number and confirm it is accepted in your test environment. If you hold Business-Scoped User IDs for users who adopted WhatsApp usernames, the optional recipient field can carry the BSUID instead of to.

Send the same template to the plain Cloud API /messages endpoint and Meta rejects it with error 131061. That is the error most teams see first after setting a max price, because their sender still points at /messages.

Errors and gotchas to plan for

For everyday codes such as 131026, 131047 and 131049, see our WhatsApp error codes guide. Also watch the account-level enrol setting whatsapp_manager_marketing_messages_max_price_enroll_status. Meta added it on 5 August 2026 and defaults non-shared accounts to OPT_IN and shared accounts to OPT_OUT. If you manage clients as a partner, check which side each account sits on before you blame your payload.

The bigger deadline: Cloud API marketing ends in 2027

The optimization_spec rename is a small fix. The larger change sits on Meta's MM API overview page:

• Messaging accounts created on or after 13 April 2027 will not be able to send marketing messages through Cloud API.
• Cloud API will stop supporting marketing messages for everyone on 13 October 2027.
• Utility messages that Meta reclassifies as marketing "must route to MM API for WhatsApp".

So every Indian business that sends promotional templates will be sending them through the Marketing Messages API within a year, whether or not it ever sets a max price. Meta says MM API keeps "the same billing model as Cloud API", reuses your existing phone numbers and templates, and that most integrations take about two weeks to go live.

The reclassification rule matters more in India than almost anywhere else. Utility templates are cheap here (₹0.115 against ₹0.8631 for marketing), so many senders push the line on what counts as utility. Once a template is recategorised, the cost jumps and, from 2027, the send route changes too. Our guide to fixing a recategorised WhatsApp template walks through appeals, and the utility vs marketing template guidelines show how to write utility copy that stays utility.

Meta's case for the move is an India A/B test with about 12 million delivered marketing messages from Indian advertisers in January 2025. Optimised delivery "drove more reads and clicks" than standard Cloud API delivery, but Meta notes the lift showed up for high-engagement messages. A weak offer stays weak on any endpoint.

What this means if you send through RichAutomate

RichAutomate sends your templates on Meta's official Cloud API at Meta's published rate card. We do not set max prices on your templates, so a max price template created elsewhere in your WhatsApp Business Account should not be pointed at RichAutomate campaigns: Meta would reject those sends with 131061. Keep the templates you send through us on rate card, which is the default when optimization_spec is absent.

The 2027 Cloud API cutoff applies to every provider, not just us. When you compare platforms this year, ask each one how and when it will move marketing sends to the Marketing Messages endpoint before 13 October 2027. A vague answer is a red flag.

Pricing stays simple while that happens. On Client Pay you pay ₹0 setup and ₹0 monthly on pay-as-you-go, plus a ₹0.10 platform fee per message, and Meta bills its own charges directly to your card. A 10,000-message opted-in campaign at rate card comes to ₹1,000 in RichAutomate fees plus about ₹8,631 to Meta, before taxes. Replies inside the 24-hour customer service window carry no Meta charge. Optional plans start at ₹499 a month, and the full breakdown is on the RichAutomate pricing page.

Migration checklist

1. Search your codebase for bid_spec in template create and update calls, and rename only those objects to optimization_spec. Leave the send-call multiplier object as Meta's current reference shows it.
2. Convert prices to paise × 1,000. ₹0.87 is 87000, ₹1.00 is 100000. A rupee value in this field is a 100× overbid or underbid waiting to happen.
3. Route max price templates to /marketing_messages and handle 131061 and 131065 with a rate card fallback.
4. Test before you scale. Run Meta's four-arm test, then ramp volume on any new max price template.
5. Send full country maps on every update, and parse the list-of-pairs format when you read them back.
6. Audit utility templates for anything that reads like a promotion before Meta moves reclassified traffic to MM API.
7. Put 13 April and 13 October 2027 in your roadmap, and get your provider's MM API migration date in writing.

Want to run opted-in WhatsApp campaigns at Meta's rate card without a monthly minimum? Create a free RichAutomate account, get your first marketing template approved, and send a test to your own number on Client Pay.