Skip to main content

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:
  1. Set a Max Price and Country multiplier on a marketing message template
  2. Optionally apply a per-message multiplier when sending a message
  3. Obtain the final charge through message status webhooks
  4. 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.
2.2.2 Adjusting the Multiplier When Sending a Template Message When sending a message using a Max Price template, you can apply a per-message multiplier greater than 0 to increase or decrease the effective Max Price for an individual message. 2.2.3 Calculate the Effective Max Price
Effective Max Price = Template maxBid x Template countryPriceAdjustments.multiplier x per_message_bid_multiplier
Example: For a template with 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.
  1. Call reachEstimate before sending to compare estimated performance at different price levels.
  2. Configure the template-level Max Price through bidSpec when creating the marketing template.
  3. Optionally pass per_message_bid_multiplier when sending a message to adjust the Max Price for an individual recipient.

4. Create a Template with Max Price

4.1 Endpoint

Add a bidSpec object when creating a marketing message template.

4.2 Request Parameters

The bidSpec object contains the following fields:

4.3 Request Example

4.4 Rules

  • Only MARKETING templates support Max Price.
  • maxBid may be lower than the published rate. Send amounts and multipliers as decimal strings, not JSON numbers.
  • If bidSpec is omitted, the template uses standard published-rate pricing.
  • Creating a template with bidSpec: {} is invalid. Supply a valid maxBid when creating with bidSpec.

4.5 Response Example

After the template is created, the response includes the template object and its bidSpec configuration.

5. Add, update, or clear Max Price

5.1 Endpoint

Use PATCH /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, or PAUSED status 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 bidSpec object. 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-level bidSpec object to either sending endpoint:
  • POST /v2/whatsapp/messages/sendDirectly submits the message synchronously.
  • POST /v2/whatsapp/messages enqueues the message for asynchronous processing.
Use the multiplier with a Max Price marketing template sent through Marketing Messages Lite. Calling the sendDirectly endpoint does not by itself select the separate Utility or Authentication Direct Send product.

6.2 Request Parameters

The message-level bidSpec object contains the following field:

6.3 Request Example

6.4 Rules

  • per_message_bid_multiplier must be greater than 0 and at most 999.999, with at most three decimal places. A value greater than 1 increases the effective Max Price, while a value between 0 and 1 decreases it.
  • The multiplier applies only to a marketing template that has Max Price enabled through bidSpec.
  • If the message request contains a bidSpec object, per_message_bid_multiplier is required. Unlike a template edit, message bidSpec: {} is invalid. To use the default multiplier of 1, omit the entire bidSpec object.

6.5 Response

The send endpoint continues to use the standard WhatsApp message response. Passing bidSpec 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 the whatsapp.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

In this example:
  • totalPrice is the final charge because the message status is delivered or read.
  • pricingCategory: marketing_lite_bidding identifies the Max Price pricing category.
  • bidPricingFlag: true confirms 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

Interpretation:
  1. 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 of 4.8% to 23.4% and an estimated cost range of approximately USD 344.46 to USD 396.
  2. 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 of 6.3% to 26.3% and an estimated cost range of approximately USD 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 is delivered 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.