Read user-wide message billing records across WhatsApp sender numbers.

User Billing History

Summary

Use Message Billing APIs to inspect user-level billing history, sender-specific billing, template-type costs, and delivered/payable/free classifications.

Prerequisites

Bearer token authentication
Billing permissions on the Whats91 account

Authentication

Use a public API token in the Authorization header. GET endpoints also accept authToken, auth_token, or token as query parameters.

Authorization header

Authorization: Bearer w91_live_xxxxxxxxxxxxxxxxx

User-wide Billing API

Endpoint: GET /api/v2/billing/messages. With a global token and no senderId, this returns billing records across the authenticated customer WhatsApp numbers.

GET/api/v2/billing/messages

Parameter	Type	Required	Description
`senderId`	string	Optional	Optional WhatsApp sender phone number. If omitted with a global token, message billing is user-wide.
`phoneNumberId`	string	Optional	Optional Meta phone number id filter. Number-scoped tokens cannot use another number.
`page`	number	Optional	Positive integer. Default 1.
`limit`	number	Optional	Positive integer. Default 50, max 200.
`dateFrom`	string	Optional	YYYY-MM-DD start date.
`dateTo`	string	Optional	YYYY-MM-DD end date.
`status`	string	Optional	accepted, sent, delivered, read, failed, pending, or another message billing status.
`templateType`	string	Optional	Meta pricing category: marketing, utility, authentication, or service.
`billable`	string	Optional	true, false, payable, or free.
`pricingType`	string	Optional	Meta pricing type, when available.
`messageId`	string	Optional	Exact Meta message id.
`recipient`	string	Optional	Recipient phone number.
`conversationId`	string	Optional	Meta conversation id.
`sortBy`	string	Optional	created_at, message_timestamp, pricing_category, status, or rate.
`sortOrder`	string	Optional	ASC or DESC.

User-wide billing history

curl "https://graph.whats91.com/api/v2/billing/messages?dateFrom=2026-06-01&limit=50" \
  -H "Authorization: Bearer w91_live_xxx"

Billing history response

{
  "success": true,
  "message": "Billing records retrieved",
  "data": {
    "senderId": "919999999999",
    "phoneNumberId": "1234567890",
    "scope": "user",
    "billingRecords": [
      {
        "billingUid": "bill_uid",
        "messageId": "wamid.xxxxx",
        "phoneNumberId": "1234567890",
        "senderPhoneNumber": "919999999999",
        "recipientId": "918888888888",
        "status": "delivered",
        "billable": true,
        "billingClass": "payable",
        "pricingModel": "PMP",
        "pricingCategory": "utility",
        "templateType": "utility",
        "pricingType": "regular",
        "rate": 0.115,
        "conversationId": "conv_xxxxx",
        "conversationOriginType": "utility",
        "messageTimestamp": "2026-06-05T08:00:00.000Z",
        "createdAt": "2026-06-05T08:00:01.000Z",
        "updatedAt": "2026-06-05T08:00:02.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "totalPages": 1,
      "count": 1,
      "hasMore": false
    }
  },
  "metadata": {
    "apiVersion": "v2",
    "requestId": "request-uuid"
  }
}

Errors

Error code	Meaning
MISSING_AUTH_TOKEN	No token was supplied.
INVALID_AUTH_TOKEN	Token is invalid, expired, revoked, or does not belong to an active customer.
SENDER_NOT_ALLOWED	A number-scoped token tried to read another sender billing.
VALIDATION_FAILED	Invalid date, pagination, template type, billable value, transaction type, or sort field.

SDK Examples

Use these examples as starting points for server-side implementations.

cURL

curl -X GET "https://graph.whats91.com/api/v2/billing/messages" \
  -H "Authorization: Bearer w91_live_xxx"

Node.js

const response = await fetch("https://graph.whats91.com/api/v2/billing/messages", {
  method: "GET",
  headers: {
    "Authorization": "Bearer w91_live_xxx",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

PHP

$ch = curl_init("https://graph.whats91.com/api/v2/billing/messages");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer w91_live_xxx",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import requests

response = requests.request(
    "GET",
    "https://graph.whats91.com/api/v2/billing/messages",
    headers={
        "Authorization": "Bearer w91_live_xxx",
        "Content-Type": "application/json",
    }
)

print(response.json())

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer w91_live_xxx");

var request = new HttpRequestMessage(HttpMethod.Get, "https://graph.whats91.com/api/v2/billing/messages");

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Frequently Asked Questions

How do I retrieve billing history?

Use GET /api/v2/billing/history with account, sender, template, classification, and date filters where supported.

What is a payable message?

A payable message is a delivered or accepted billing record that counts toward the customer billing model according to Whats91 and Meta rules.

Can I filter by sender number?

Yes. Use the number-specific billing history endpoint to review billing records for one sender.

User Billing History

Summary

Prerequisites

Related documentation

Authentication

User-wide Billing API

Errors

SDK Examples

Frequently Asked Questions

How do I retrieve billing history?

What is a payable message?

Can I filter by sender number?

Related APIs

Number History

Template Type

Reports

Delivery Analytics