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:

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:

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

Call reachEstimate before sending to compare estimated performance at different price levels.
Configure the template-level Max Price through bidSpec when creating the marketing template.
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
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

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.

{
  "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}
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

5.3 Rules

You cannot addbidSpec to an existing template that was created without it. You must create a new template withbidSpec 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
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

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.

{
  "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

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 deliveredorread.
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:

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

{
  "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:

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.
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.

​1. Overview

​2. Core Concepts

​2.1 What Is a Max Price?

​2.2 How to Set the Max Price

​2.3 Dynamic Charging Rules

​2.4 What Is the Reach Estimation Tool?

​3. Recommended Integration Flow

​4. Create a Template with Max Price

​4.1 Endpoint

​4.2 Request Parameters

​4.3 Request Example

​4.4 Rules

​4.5 Response Example

​5. Update a Max Price on a Template

​5.1 Endpoint

​5.2 Request Parameters & Example

​4. Create a Template with Max Price

​5.3 Rules

​6. Set a Per-Message Bid Multiplier When Sending a Message

​6.1 Endpoint

​6.2 Request Parameters

​6.3 Request Example

​6.4 Rules

​6.5 Response

​7. Final Charges and Message Status Webhooks

​7.1 Webhook Event

​7.2 Webhook Payload Example

​8. Estimate Delivery and Cost Before Sending

​8.1 Endpoint

​8.2 Request Parameters

​8.3 Response Structure

​8.4 Response Example

​Frequently Asked Questions

​Can I know the actual delivery price for a specific recipient before sending?

​Why do the actual delivery results differ from the estimate?

​Will the actual charge be returned after a message is delivered?

1. Overview

2. Core Concepts

2.1 What Is a Max Price?

2.2 How to Set the Max Price

2.3 Dynamic Charging Rules

2.4 What Is the Reach Estimation Tool?

3. Recommended Integration Flow

4. Create a Template with Max Price

4.1 Endpoint

4.2 Request Parameters

4.3 Request Example

4.4 Rules

4.5 Response Example

5. Update a Max Price on a Template

5.1 Endpoint

5.2 Request Parameters & Example

4. Create a Template with Max Price

5.3 Rules

6. Set a Per-Message Bid Multiplier When Sending a Message

6.1 Endpoint

6.2 Request Parameters

6.3 Request Example

6.4 Rules

6.5 Response

7. Final Charges and Message Status Webhooks

7.1 Webhook Event

7.2 Webhook Payload Example

8. Estimate Delivery and Cost Before Sending

8.1 Endpoint

8.2 Request Parameters

8.3 Response Structure

8.4 Response Example

Frequently Asked Questions

Can I know the actual delivery price for a specific recipient before sending?

Why do the actual delivery results differ from the estimate?

Will the actual charge be returned after a message is delivered?