WhatsApp Message Pricing Integration Guide

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

Getting Started

Guides

Endpoints

Webhooks

WhatsApp Message Pricing Integration Guide

1. Subscription event

2. Pricing fields

3. Pricing rules

3.1 Price finality

3.2 Billable and free pricing types

4. Webhook payload examples

4.1 Marketing message: billable

4.2 Service message: billable

4.3 Service message: within the free allowance

4.4 Free-entry point message

​1. Subscription event

​2. Pricing fields

​3. Pricing rules

​3.1 Price finality

​3.2 Billable and free pricing types

​4. Webhook payload examples

​4.1 Marketing message: billable

​4.2 Service message: billable

​4.3 Service message: within the free allowance

​4.4 Free-entry point message

1. Subscription event

2. Pricing fields

3. Pricing rules

3.1 Price finality

3.2 Billable and free pricing types

4. Webhook payload examples

4.1 Marketing message: billable

4.2 Service message: billable

4.3 Service message: within the free allowance

4.4 Free-entry point message