> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Max Price Integration Guide
This feature is currently in beta. To request access, please contact YCloud.
## 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:
| Pricing strategy | Objective | Expected outcome |
| - | - | - |
| Same as the published rate | Control costs while maintaining delivery rates similar to existing WhatsApp campaigns | Potentially lower costs while maintaining a similar delivery level |
| Lower than the published rate | Reach suitable customer cohorts at a lower cost | Reduce the maximum acceptable price per message, although delivery volume may change accordingly |
| Higher than the published rate | Improve delivery rates during holidays, major promotions, or peak sales periods | Increase competitiveness and improve the opportunity for more messages to be delivered |
**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:
You created a template, and template-level Max price settings as follows
* maxBid：0.1 USD，
* countryPriceAdjustments.multiplier:
* IN: 0.8x
* MY: 1.3x
Then there are 4 recipients; you send them with different Per-message multiplier\*\*,\*\* the Effective Max Prices are calculated as follows:
| Recipients | Per-message multiplier applied | CountryCountry | **Effective Max PriceEffective Max Price** |
| - | - | - | - |
| Mike | 1.2 | IN | 0.1(maxBid) x 0.8(IN multiplier) x 1.2(per-message multiplier) = 0.096 USD |
| Bob | 0.5 | MY | 0.1(maxBid) \* 1.3(**MY** multiplier) \* 0.5(per-message multiplier)= 0.065 USD |
| Jane | 0.7 | SG | 0.1(maxBid) x 1(default multiplier) x 0.7(per-message multiplier) = 0.07 USD |
| Jack | None | IN | 0.1(maxBid) \* 0.8(**IN** multiplier) \* 1(defualt multiplier)= 0.08 USD |
### 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
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.
* Endpoint: [https://api.ycloud.com/v2/whatsapp/templates](https://api.ycloud.com/v2/whatsapp/templates)
* Use case: Set a template-level Max Price when creating a marketing template
### 4.2 Request Parameters
The `bidSpec` object contains the following fields:
| Field | Type | Required | Description |
| - | - | - | - |
| `maxBid` | string | Required if `bidSpec`provided | Maximum price allowed by the template. The currency defaults to your YCloud billing currency.
|
| `countryPriceAdjustments` | string | No | Map of destination country to a bid multiplier. Countries you do not list use a multiplier of `1.0` (the unmodified `maxBid`).
Up to 50 entries.
Up to 50 entries. |
| `countryPriceAdjustments.countryCode` | string | Required if `countryPriceAdjustments`provided | Keys must be valid ISO 3166-1 alpha-2 country codes (for example, `MX`, `IN`, `BR`). |
| `countryPriceAdjustments.multiplier` | string | Required if `countryPriceAdjustments`provided | Each multiplier must be greater than `0` and at most `10`. |
### 4.3 Request Example
```bash highlight={11-23} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
--url 'https://api.ycloud.com/v2/whatsapp/templates' \
--header 'X-API-Key: {{YOUR_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"category": "MARKETING",
"wabaId": "{{YOUR_WABA_ID}}",
"name": "market",
"language": "en",
"bidSpec": {
"maxBid": "0.123",
"countryPriceAdjustments": [
{
"countryCode": "CN",
"multiplier": "1.9"
},
{
"countryCode": "ID",
"multiplier": "1.3"
}
]
},
"components": [
{
"type": "BODY",
"text": "Hi, Black Friday is coming!"
}
]
}'
```
### 4.4 Rules
* `maxBid` must be greater than `0` and may be lower than the published rate.
* If `bidSpec` is omitted, the template uses standard published-rate pricing.
### 4.5 Response Example
After the template is created, the response includes the template object and its `bidSpec` configuration.
```json highlight={6-18} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"officialTemplateId": "1763024734605057",
"wabaId": "{{YOUR_WABA_ID}}",
"name": "marketing_friday",
"language": "en",
"bidSpec": {
"maxBid": "0.123",
"countryPriceAdjustments": [
{
"countryCode": "CN",
"multiplier": "1.9"
},
{
"countryCode": "ID",
"multiplier": "1.3"
}
]
},
"messageSendTtlSeconds": -1,
"components": [
{
"type": "BODY",
"text": "Hi, Black Friday is coming!"
}
],
"category": "MARKETING",
"status": "PENDING",
"qualityRating": "UNKNOWN",
"createTime": "2026-08-12T15:18:42.356Z",
"updateTime": "2026-08-12T15:18:42.356Z",
"ctaUrlLinkTrackingOptedOut": true
}
```
## 5. Update a Max Price on a Template
### 5.1 Endpoint
Add a `bidSpec` object when updatinging a marketing message template.
* Endpoint: [https://api.ycloud.com/v2/whatsapp/templates/\{wabaId}/\{name}/\{language}](https://docs.ycloud.com/reference/whatsapp_template-edit-by-name-and-language)
* Use case: Adjust max price
### 5.2 Request Parameters & Example
Refer to [Create a Template with Max Price](#4-create-a-template-with-max-price)
## 4. Create a Template with Max Price
### 5.3 Rules
* You cannot add`bidSpec` to an existing template that was created without it. You must create a new template with`bidSpec` included.
* **Approved templates**: Up to 100 edits per hour, 2,400 per day. Content edits still follow the existing limit of 1 per day and 10 per 30 days.
* **Rejected or paused templates**: Unlimited edits
## 6. Set a Per-Message Bid Multiplier When Sending a Message
### 6.1 Endpoint
Add a `bidSpec` object when sending a message directly.
* Endpoint: [https://api.ycloud.com/v2/whatsapp/messages/sendDirectly](https://api.ycloud.com/v2/whatsapp/messages/sendDirectly)
* Use case: Adjust the effective Max Price for an individual recipient
### 6.2 Request Parameters
The message-level `bidSpec` object contains the following field:
| Field | Type | Required | Description |
| - | - | - | - |
| `per_message_bid_multiplier` | string | Conditional | Multiplier applied to the template-level effective Max Price for this message. Must be greater than 0 and supports up to three decimal places. If `bidSpec` is included in the request, this field is required. To use the default multiplier of `1`, omit the entire `bidSpec` object. |
### 6.3 Request Example
```bash highlight={8-9} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
--url 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
--header 'X-API-Key: {{YOUR_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"type": "template",
"bidSpec": {
"per_message_bid_multiplier": "1.2"
},
"template": {
"language": {
"code": "en"
},
"name": "marketing_friday"
},
"from": "+1555*****",
"to": "+62*****"
}'
```
### 6.4 Rules
* `per_message_bid_multiplier` must be greater than 0 and supports up to 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. 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 rather than the final charge.
```json highlight={18} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "6a7c922697330900cf11ca2f",
"wamid": "wamid.HBgNODYxNTA2NzExMDI0NBUCABEYEkE1REJGMkIzOTMwQ0VENUIyMAA=",
"status": "accepted",
"from": "+1555*****",
"to": "+62*****",
"wabaId": "{{YOUR_WABA_ID}}",
"type": "template",
"template": {
"name": "marketing_friday",
"language": {
"code": "en"
}
},
"createTime": "2026-08-12T15:32:54.571Z",
"updateTime": "2026-08-12T15:32:55.228Z",
"totalPrice": 0.1845,
"pricingCategory": "marketing_lite_bidding",
"currency": "USD",
"regionCode": "ID",
"bizType": "whatsapp"
}
```
## 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.
| Field | New field/value | Description |
| - | - | - |
| `bidPricingFlag` | New field | Boolean. `true` indicates that the message was sent using Max Price pricing; `false` indicates standard published-rate pricing |
| `pricingCategory` | New value | Max Price marketing messages use `marketing_lite_bidding` |
| `totalPrice` | Existing field | Dynamic message price. The value may differ by recipient. It becomes the final charge when the message status is `delivered` or `read` |
### 7.2 Webhook Payload Example
```bash highlight={28-30} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
--header 'Content-Type: application/json' \
--data '{
"id": "evt_6a7d30d9c038963ead5945f3",
"type": "whatsapp.message.updated",
"apiVersion": "v2",
"createTime": "2026-08-13T02:50:01.057Z",
"whatsappMessage": {
"id": "6a7d30c92733962aed9f0fda",
"wamid": "wamid.HBgLNTE5OTc5NTMwOTQVAgARGBI5MUJBNTE0Qjk4Q0E5NTIzMDgA",
"status": "read",
"from": "+1555***",
"to": "+62***",
"wabaId": "{{YOUR_WABA_ID}}",
"recipient": "ID.12*******",
"type": "template",
"template": {
"name": "marketing_friday",
"language": {
"code": "en"
},
"components": []
},
"createTime": "2026-08-13T02:49:45.403Z",
"sendTime": "2026-08-13T02:49:50.000Z",
"deliverTime": "2026-08-13T02:49:50.000Z",
"readTime": "2026-08-13T02:50:00.000Z",
"totalPrice": 0.0703,
"pricingCategory": "marketing_lite_bidding",
"bidPricingFlag": true,
"pricingType": "regular",
"pricingModel": "PMP",
"currency": "USD",
"regionCode": "ID",
"bizType": "whatsapp",
"recipientUserId": "ID.12*******"
}
}'
```
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
| Parameter | Type | Required | Description |
| - | - | - | - |
| `wabaId` | string | Yes | WhatsApp Business Account ID |
| `targetCountry` | string | Yes | Target country code. Keys must be valid ISO 3166-1 alpha-2 country codes (for example, `MX`, `IN`, `BR`).. Keys must be valid ISO 3166-1 alpha-2 country codes (for example, `MX`, `IN`, `BR`). |
| `dateInterval` | string | No | Lookback period for the historical data used to generate estimates. One of: `L1D` (last 1 day), `L7D` (last 7 days), `L14D` (last 14 days), `L28D` (last 28 days).
Default `L28D` |
Request example:
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate?targetCountry=MX&dateInterval=L7D
```
### 8.3 Response Structure
| Field | Type | Description |
| - | - | - |
| `waba_currency` | string | Currency of the WABA |
| `estimates` | array | List of estimated price levels |
| `dateInterval` | string | Lookback period for the historical data used to generate estimates |
Each item in `estimates` contains:
| Field | Type | Description |
| - | - | - |
| `bid_amount` | number | Maximum amount the business is willing to pay for a batch of 1,000 recipients |
| `users` | number | Number of target recipients; currently fixed at `1000` |
| `deliveries_lower_bound` | string | Estimated minimum number of delivered messages per 1,000 recipients |
| `deliveries_upper_bound` | string | Estimated maximum number of delivered messages per 1,000 recipients |
| `cost_lower_bound` | number | Estimated minimum cost for the batch |
| `cost_upper_bound` | number | Estimated maximum cost for the batch |
### 8.4 Response Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"waba_currency": "USD",
"dateInterval": "L7D",
"estimates": [
{
"bid_amount": 395,
"users": 1000,
"deliveries_lower_bound": 48,
"deliveries_upper_bound": 234,
"cost_lower_bound": 344.46,
"cost_upper_bound": 396
},
{
"bid_amount": 495,
"users": 1000,
"deliveries_lower_bound": 63,
"deliveries_upper_bound": 263,
"cost_lower_bound": 353.067,
"cost_upper_bound": 429.597
}
]
}
```
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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.