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

# WhatsApp Message Pricing Integration Guide

> Understand WhatsApp message pricing fields, charging rules, and price finality in YCloud webhooks.

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](/api-reference/webhook-endpoints/create-a-webhook-endpoint) for the endpoint reference:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.ycloud.com/v2/webhookEndpoints
Content-Type: application/json
X-API-Key: YOUR_YCLOUD_API_KEY
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/en/api-reference/guides/api-fundamentals/configure-webhooks).

## 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](/api-reference/whatsapp-messages/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](/en/documentation/pricing-and-billing/whatsapp-pricing-and-billing), 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](/en/api-reference/guides/examples/webhook-examples/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`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000004",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "free_entry_point",
    "pricingCategory": "referral_conversion",
    "totalPrice": 0,
    "currency": "USD"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.