data object[]

List of usage records, grouped according to the groupBy parameter.

Array [

subAccountIdstring

Sub-account identifier. Present when subAccountId is included in groupBy.

Example: umsg_AGG001

channelstring

Messaging channel. Present when channel is included in groupBy.

Possible values: [whatsapp]

Example: whatsapp

countrystring

ISO 3166-1 alpha-2 destination country code. Present when country is included in groupBy.

Example: IN

businessAccountIdstring

Business account identifier associated with the messaging provider. For WhatsApp, this represents the WhatsApp Business Account (WABA) ID. Present when businessAccountId is included in groupBy.

Example: 120xx01234567890

pricingCategorystring

Message pricing category. For WhatsApp: utility, marketing, authentication, authentication_international, service. Present when pricingCategory is included in groupBy.

Example: utility

volume object

Message volume breakdown.

deliveredinteger

Total number of delivered messages.

Example: 479100

chargedinteger

Number of messages that were charged.

Example: 437900

freeinteger

Number of messages delivered at no charge.

Example: 41200

pricing object

Pricing structure. Present when groupBy includes channel, businessAccountId, pricingCategory, and country.

rateModelstring

The pricing rate model applied to this combination.

Possible values: [flat, tiered]

Example: tiered

tiers object[]

Tier breakdown. Only present when rateModel is tiered.

Array [

frominteger

Lower bound of this tier (inclusive).

Example: 0

tointeger

Upper bound of this tier (inclusive). null indicates an openended bracket with no upper limit.

Example: 250000

quantityinteger

Number of messages that fall within this tier.

Example: 250000

statusstring

Indicates the tier was fully settled. Always completed since only closed billing periods can be queried.

Possible values: [completed]

Example: completed

]

]

meta object

Metadata about the request and result set.

accountIdstring

The account ID used in the request.

Example: bp-xxx

billingPeriod object

startstring<date>

Start date of the billing period.

Example: 2026-03-01

endstring<date>

End date of the billing period.

Example: 2026-03-31

statusstring

The billing period status. Always closed since only closed billing periods can be queried.

Possible values: [closed]

Example: closed

dataAsOfstring<date-time>

Timestamp the final data snapshot for this billing period.

Example: 2026-03-16T12:00:00Z

groupBystring[]

The groupBy dimensions applied to this query.

Example: ["subAccountId","channel","businessAccountId","pricingCategory","country"]

currencystring

Currency used for pricing amounts (ISO 4217 code).

Example: USD

{
"data":[
{
"subAccountId":"umsg_AGG001",
"channel":"whatsapp",
"country":"IN",
"businessAccountId":"120xx01234567890",
"pricingCategory":"utility",
"volume":{
"delivered":479100,
"charged":437900,
"free":41200
},
"pricing":{
"rateModel":"tiered",
"tiers":[
{
"from":0,
"to":250000,
"quantity":250000,
"status":"completed"
}
]
}
}
],
"meta":{
"accountId":"bp-xxx",
"billingPeriod":{
"start":"2026-03-01",
"end":"2026-03-31",
"status":"closed"
},
"dataAsOf":"2026-03-16T12:00:00Z",
"groupBy":[
"subAccountId",
"channel",
"businessAccountId",
"pricingCategory",
"country"
],
"currency":"USD"
}
}

{
"data":[
{
"subAccountId":"umsg_AGG001",
"channel":"whatsapp",
"country":"IN",
"businessAccountId":"120xx01234567890",
"pricingCategory":"utility",
"volume":{
"delivered":479100,
"charged":437900,
"free":41200
},
"pricing":{
"rateModel":"tiered",
"tiers":[
{
"from":0,
"to":250000,
"quantity":250000,
"status":"completed"
},
{
"from":250001,
"to":500000,
"quantity":187900,
"status":"completed"
}
]
}
},
{
"subAccountId":"umsg_AGG001",
"channel":"whatsapp",
"country":"IN",
"businessAccountId":"120xx01234567890",
"pricingCategory":"marketing",
"volume":{
"delivered":1234,
"charged":1234,
"free":0
},
"pricing":{
"rateModel":"flat"
}
}
],
"meta":{
"accountId":"bp-xxx",
"billingPeriod":{
"start":"2026-03-01",
"end":"2026-03-31",
"status":"closed"
},
"dataAsOf":"2026-03-16T12:00:00Z",
"groupBy":[
"subAccountId",
"channel",
"businessAccountId",
"pricingCategory",
"country"
],
"currency":"USD"
}
}

{
"data":[
{
"volume":{
"delivered":480334,
"charged":439134,
"free":41200
}
}
],
"meta":{
"accountId":"bp-xxx",
"billingPeriod":{
"start":"2026-03-01",
"end":"2026-03-31",
"status":"closed"
},
"dataAsOf":"2026-03-16T12:00:00Z",
"groupBy":[],
"currency":"USD"
}
}

codeintegerrequired

Error code

messagestring

Error description

errorIdstring<uuid>required

Unique id of error. You can use it as reference when sending enquiries to 8x8 support

timestampstring<date-time>required

Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}

codeintegerrequired

Error code

messagestring

Error description

errorIdstring<uuid>required

Unique id of error. You can use it as reference when sending enquiries to 8x8 support

timestampstring<date-time>required

Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}