Using API to Check Customer's Bills

This document describes how white-label partners can query customers' WhatsApp fees through the API

You can obtain the WhatsApp fees for your site's customers by calling the daily billing API.

Daily Billing Interface

Interface URL: https://api.ycloud.com/v2/billing/usageDetails

Function Description: Returns billing data by day, paginated. Grouping criteria: date (daily, fixed UTC+8 time zone), sending region, message channel (WhatsApp, SMS, voice, email), WABA ID (only applicable for WhatsApp channel). Sorting: by date in descending order.

Request Method: GET

Request Headers:

Parameter	Description
X-API-Key	[Required] Account API Key, see Console.
X-Managed-Account-ID	Applicable only for white-label partners. If your account has one or more managed accounts, you can specify a managed account ID, which will make the request as the managed account and retrieve its billing data.

Request Parameters:

Parameter	Description
page	Page number, integer, range [1,100]. Default is 1.
limit	Page size, integer, range [1,100]. Default is 10.
includeTotal	Whether to return the total record count, values true / false, default is false.
filter.startDate	[Required] Billing start date (inclusive), format yyyy-MM-dd, example 2024-01-31
filter.endDate	[Required] Billing end date (inclusive), format yyyy-MM-dd, example 2024-01-31
filter.wabaId	WABA ID

Request Example:

curl 'https://api.ycloud.com/v2/billing/usageDetails?page=1&limit=10&includeTotal=false&filter.startDate=2024-01-01&filter.endDate=2024-01-31&filter.wabaId=WABA-ID' \
-H 'X-API-Key: {{YOUR-API-KEY}}'

Response Example:

{
  "offset": 0,
  "limit": 10,
  "total": 1,
  "length": 1,
  "items": [
    {
      "date": "2024-03-06",
      "isTransient": true,
      "channel": "whatsapp",
      "wabaId": "WABA_ID",
      "regionCode": "CN",
      "costItems": [
        {
          "cost": 1.0,
          "unitPrice": 0.1,
          "quantity": 10,
          "conversationOriginType": "authentication"
        },
        {
          "cost": 3.0,
          "unitPrice": 0.2,
          "quantity": 15,
          "conversationOriginType": "utility"
        }
      ]
    }
  ]
}

Response Fields:

Common fields like offset, limit, etc., are omitted, see Pagination.

The fields of the returned items[] object are as follows:

Field	Type	Description
date	string	Billing date, format yyyy-MM-dd, example 2024-01-31
isTransient	boolean	Whether it's temporary. For nearly real-time bills from yesterday or today, it might not be accurate and can change, marked as true. If false, it means the bill is final.
channel	string	Message channel. Enumeration: whatsapp, sms, voice, email.
wabaId	string	WABA ID. Included when channel is whatsapp.
regionCode	string	Region where the message was sent, two-letter country or region codes.
costItems[].cost	double	Amount consumed, in USD
costItems[].quantity	integer	Number of billed messages
costItems[].unitPrice	double	Average unit price
costItems[].conversationOriginType	string	WhatsApp conversation type. Included only when channel is whatsapp. Enumeration: authentication, authentication_international, marketing, utility, service.