English / 简体中文
YCloud provides per-message pricing information through WhatsApp message-update webhooks. This guide describes the subscription event, pricing fields, charging rules, and when message prices become final.
YCloud charges only for outbound WhatsApp messages (messages sent from your business to users). Inbound messages are free.
1. Subscription event
YCloud sends message status and pricing updates through the whatsapp.message.updated event. Subscriptions are available under Developers → Webhook in the YCloud Console.
The following request creates a subscription through the API. See Create a webhook endpoint for the endpoint reference:
POST https://api.ycloud.com/v2/webhookEndpoints
Content-Type: application/json
X-API-Key: YOUR_YCLOUD_API_KEY{
"url": "https://example.com/webhooks/ycloud",
"enabledEvents": ["whatsapp.message.updated"],
"status": "active"
}url specifies the webhook receiving endpoint. Event handling and signature verification are described in the Webhook Integration Guide.
2. Pricing fields
Pricing information is included in the callback's whatsappMessage object:
| Field | Description |
|---|---|
pricingModel | Always PMP, meaning per-message pricing. |
pricingType | The message's billable or free pricing type. |
pricingCategory | The message's pricing category, such as marketing, utility, authentication, service, or referral_conversion (free entry point). When pricingType=free_entry_point, this field is referral_conversion. |
totalPrice | The amount reported by YCloud for this message. |
currency | The currency of the amount, such as USD, taken from the tenant's currency setting. |
Other fields are described in Retrieve a message.
3. Pricing rules
3.1 Price finality
YCloud reports estimated or final prices according to the message status:
| Message status | Price meaning |
|---|---|
accepted / sent | Estimated price. |
delivered / read | Final price. Billing uses the totalPrice and currency reported at this stage. |
failed | Sending failed. YCloud does not charge for the message. |
3.2 Billable and free pricing types
YCloud reports the following three pricing types through pricingType:
pricingType | Meaning |
|---|---|
regular | Regular billable pricing. The actual amount reported by YCloud is in totalPrice. |
free_customer_service | A free message within the customer service window. YCloud reports an amount of 0. Under the WhatsApp pricing update, effective October 1, 2026, each business phone number receives 1,000 free delivered service messages per month. One-to-one service messages within this allowance continue to use this pricing type. |
free_entry_point | A free-entry point message covered by the 72-hour free-entry point rules. Its pricingCategory is referral_conversion, and YCloud reports an amount of 0. |
Effective October 1, 2026, the service allowance resets monthly for each business phone number. Unused allowance does not roll over, and one-to-one and group service messages share the same allowance. Once it is exhausted, one-to-one service messages use regular pricing unless the free-entry point rules apply.
From the same date, utility templates within the customer service window are no longer free solely because the window is open and are not covered by the service allowance. Messages eligible for free-entry point pricing continue to use free_entry_point.
A free-entry point window opens when a user sends a message to a business through an ad that clicks to WhatsApp or a WhatsApp button on a Facebook Page using WhatsApp for Android or iOS, and the business replies within 24 hours. The window lasts 72 hours from the business's reply. WhatsApp desktop and web clients are not eligible for this entry-point rule.
4. Webhook payload examples
The following callback excerpts represent one-to-one messages. IDs and charge amounts are illustrative, not actual rate quotes. For complete payloads, see WhatsApp Message Updated Webhook Examples.
4.1 Marketing message: billable
A delivered marketing message uses regular pricing. The illustrative final amount is 0.05 USD.
{
"type": "whatsapp.message.updated",
"whatsappMessage": {
"id": "66eb00000000000000000001",
"status": "delivered",
"pricingModel": "PMP",
"pricingType": "regular",
"pricingCategory": "marketing",
"totalPrice": 0.05,
"currency": "USD"
}
}4.2 Service message: billable
Effective October 1, 2026, when the business phone number has exhausted its monthly allowance of 1,000 free service messages and the message is not eligible for free-entry point pricing, YCloud reports pricingType=regular. The illustrative final amount is 0.01 USD.
{
"type": "whatsapp.message.updated",
"whatsappMessage": {
"id": "66eb00000000000000000002",
"status": "delivered",
"pricingModel": "PMP",
"pricingType": "regular",
"pricingCategory": "service",
"totalPrice": 0.01,
"currency": "USD"
}
}4.3 Service message: within the free allowance
Effective October 1, 2026, for a message covered by the business phone number's monthly allowance of 1,000 free service messages, YCloud reports pricingType=free_customer_service and a final amount of 0.
{
"type": "whatsapp.message.updated",
"whatsappMessage": {
"id": "66eb00000000000000000003",
"status": "delivered",
"pricingModel": "PMP",
"pricingType": "free_customer_service",
"pricingCategory": "service",
"totalPrice": 0,
"currency": "USD"
}
}4.4 Free-entry point message
For a message delivered within the 72-hour free-entry point window, YCloud reports pricingType=free_entry_point, pricingCategory=referral_conversion, and a final amount of 0.
{
"type": "whatsapp.message.updated",
"whatsappMessage": {
"id": "66eb00000000000000000004",
"status": "delivered",
"pricingModel": "PMP",
"pricingType": "free_entry_point",
"pricingCategory": "referral_conversion",
"totalPrice": 0,
"currency": "USD"
}
}