1. Overview
To help businesses gain greater control over and optimize their WhatsApp marketing messaging spend, YCloud supports the new pricing capabilities introduced by Meta for the Marketing Messages API in 2026, including Max Price and the Reach Estimation Tool. With the YCloud API, businesses can set the maximum price they are willing to pay for each delivered WhatsApp marketing message and adjust their pricing strategy based on campaign cost and delivery objectives. When a Max Price is set, Meta charges that price or lower for each delivered message. Before sending, businesses can also use the Reach Estimation Tool to understand the estimated delivery volume and cost at different Max Price levels. This guide explains how to use the YCloud API to:- Set a Max Price and Country multiplier on a marketing message template
- Optionally apply a per-message multiplier when sending a message
- Obtain the final charge through message status webhooks
- Estimate delivery volume and cost at different Max Price levels before sending
2. Core Concepts
2.1 What Is a Max Price?
A Max Price is the maximum amount a business is willing to pay for each successfully delivered WhatsApp marketing message. When a Max Price is set, Meta charges that price or lower for delivery. The actual charge will not exceed the configured price limit. Depending on the objective of a marketing campaign, a business can set its Max Price at, below, or above Meta’s published rate:
A Max Price is a price ceiling, not a fixed charge. Setting a Max Price does not mean that every delivered message will be charged at that price. The price of each message is calculated dynamically and may be equal to or lower than the configured Max Price.
2.2 How to set the Max Price
2.2.1 Setting the Maximum Price on a Template You can set a fixed Max price(maxBid) for a template and configure different multipliers(countryPriceAdjustments.multiplier) for different countries or regions. For example, suppose the maxBid is set to USD 0.10, with a 0.8× multiplier for India and a 1.3× multiplier for Malaysia:
- When the template is used to send a message to India, the template-level Max price is USD 0.10 × 0.8 = USD 0.08.
- When the template is used to send a message to Malaysia, the template-level Max price USD 0.10 × 1.3 = USD 0.13.
- When the template is sent to any other country, the template-level Max price is USD 0.10.
Effective Max Price = Template maxBid x Template countryPriceAdjustments.multiplier x per_message_bid_multiplier
maxBid: "0.1" in USD, country multipliers of 0.8 for India and 1.3 for Malaysia produce these effective price ceilings:
Amounts use your YCloud billing currency. Countries without an override use a multiplier of
1. Omit the entire message-level bidSpec object to use a per-message multiplier of 1.
2.3 Dynamic Charging Rules
The price of each successfully delivered message is calculated dynamically for its recipient:- The Max Price configured on the template represents only the maximum amount the business is willing to pay.
- The final charge for a delivery message is dynamic; Meta charges at that max price or lower for delivery.
- Different recipients in the same send may have different actual message prices.
- Messages that are not delivered do not incur a delivery charge.
- A Max Price affects bidding and the opportunity for delivery, but does not guarantee delivery. Actual results may also be affected by real-time bidding, recipient status, and Meta eligibility checks.
2.4 What Is the Reach Estimation Tool?
The Reach Estimation Tool helps businesses select an appropriate Max Price. Before sending, businesses can use the estimation endpoint to view the estimated delivery volume and cost range at different Max Price levels, and then choose a pricing strategy based on their campaign objectives and budget. Estimates are provided for planning purposes only and do not guarantee actual delivery results or final billing amounts. Actual results may be affected by real-time bidding, recipient status, and Meta eligibility checks.3. Recommended Integration Flow
- Call
reachEstimatebefore sending to compare estimated performance at different price levels. - Configure the template-level Max Price through
bidSpecwhen creating the marketing template. - Optionally pass
per_message_bid_multiplierwhen sending a message to adjust the Max Price for an individual recipient.
4. Create a Template with Max Price
4.1 Endpoint
Add abidSpec object when creating a marketing message template.
- Endpoint: https://api.ycloud.com/v2/whatsapp/templates
- Use case: Set a template-level Max Price when creating a marketing template
4.2 Request Parameters
ThebidSpec object contains the following fields:
4.3 Request Example
4.4 Rules
- Only
MARKETINGtemplates support Max Price. maxBidmay be lower than the published rate. Send amounts and multipliers as decimal strings, not JSON numbers.- If
bidSpecis omitted, the template uses standard published-rate pricing. - Creating a template with
bidSpec: {}is invalid. Supply a validmaxBidwhen creating withbidSpec.
4.5 Response Example
After the template is created, the response includes the template object and itsbidSpec configuration.
5. Add, update, or clear Max Price
5.1 Endpoint
UsePATCH /v2/whatsapp/templates/{wabaId}/{name}/{language} to edit a marketing template, including one created without Max Price.
5.2 Choose the edit behavior
An object whose properties are all
null, such as {"maxBid": null, "countryPriceAdjustments": null}, also clears the settings. Empty strings, empty arrays, and other non-null properties do not count as an empty configuration. For example, {"countryPriceAdjustments": []} without a valid maxBid is invalid.
To add or update Max Price, use the fields in Create a template with Max Price. Include the complete country list you want to store. The submitted list replaces the locally stored list; omitting it or sending an empty list does not explicitly clear country overrides already stored by Meta. To remove all bidding settings, send bidSpec: {}.
Include every component you want to retain. The following example clears the bidding configuration and retains the body:
5.3 Rules
- Adding, updating, and clearing Max Price follow the existing template edit flow and Meta validation. Only templates in
APPROVED,REJECTED, orPAUSEDstatus can be edited. - Supply the components you want to retain even when you only change pricing. A successful edit follows the existing review and status-synchronization flow.
- After a successful clear, the template response no longer contains a
bidSpecobject. If Meta or local persistence fails, the endpoint returns an error.
6. Set a Per-Message Bid Multiplier When Sending a Message
6.1 Endpoint
Add a message-levelbidSpec object to either sending endpoint:
POST /v2/whatsapp/messages/sendDirectlysubmits the message synchronously.POST /v2/whatsapp/messagesenqueues the message for asynchronous processing.
sendDirectly endpoint does not by itself select the separate Utility or Authentication Direct Send product.
6.2 Request Parameters
The message-levelbidSpec object contains the following field:
6.3 Request Example
6.4 Rules
-
per_message_bid_multipliermust be greater than0and at most999.999, with at most three decimal places. A value greater than1increases the effective Max Price, while a value between0and1decreases it. -
The multiplier applies only to a marketing template that has Max Price enabled through
bidSpec. -
If the message request contains a
bidSpecobject,per_message_bid_multiplieris required. Unlike a template edit, messagebidSpec: {}is invalid. To use the default multiplier of1, omit the entirebidSpecobject.
6.5 Response
The send endpoint continues to use the standard WhatsApp message response. PassingbidSpec does not introduce a separate response structure.
When the returned status is accepted, totalPrice is an estimated price. In this example, the US recipient has no country override, so 0.05 x 1 x 1.1 = 0.055 USD. Use the delivered/read webhook for the final charge.
7. Final Charges and Message Status Webhooks
7.1 Webhook Event
YCloud sends thewhatsapp.message.updated webhook event when the status of a WhatsApp message changes. For messages sent using Max Price, the webhook identifies the pricing mode and provides the final charge after the message is delivered.
7.2 Webhook payload example
totalPriceis the final charge because the message status isdeliveredorread.pricingCategory: marketing_lite_biddingidentifies the Max Price pricing category.bidPricingFlag: trueconfirms that the message was sent using Max Price pricing.
8. Estimate Delivery and Cost Before Sending
8.1 Endpoint
- Endpoint:
GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate - Use case:Use the reach estimation endpoint before sending to view estimated delivery and cost ranges at different price levels.
8.2 Request Parameters
Request example:
8.3 Response Structure
Each item in
estimates contains:
8.4 Response Example
- When the Max Price per message is
395 / 1000 USD = USD 0.395, a batch of 1,000 recipients has an estimated delivery-rate range of4.8% to 23.4%and an estimated cost range of approximatelyUSD 344.46 to USD 396. - When the Max Price per message is
495 / 1000 USD = USD 0.495, a batch of 1,000 recipients has an estimated delivery-rate range of6.3% to 26.3%and an estimated cost range of approximatelyUSD 353.067 to USD 429.597.
Frequently Asked Questions
Can I know the actual delivery price for a specific recipient before sending?
No. The delivery price for each recipient is dynamic and cannot be known in advance. The business only needs to set the maximum price it is willing to pay. A successfully delivered message is charged at its actual delivery price, which will not exceed the effective Max Price.Why do the actual delivery results differ from the estimate?
The estimation endpoint provides reference values only. Actual results may be affected by real-time bidding, recipient status, and Meta eligibility checks. If the difference is significant, contact YCloud for assistance.Will the actual charge be returned after a message is delivered?
Yes. When the message status isdelivered or read, totalPrice represents the final charge based on the recipient’s actual delivery price. When the message is initially accepted or its status is sent, YCloud returns an estimated price rather than the final charge.
