Balance & Usage

Endpoints for retrieving balance information and usage analytics

Retrieve the balance information for a partner

get

The "Get Partner Balance" endpoint is a part of our API that enables partner users to retrieve the partner balance. This endpoint is particularly useful for partners who have prepaid accounts with us and are responsible for making payments based on their usage of our services.

There can be multiple balance records for a partner, if partner's balance is topped-up in different currencies.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The partner_id path parameter

Responses

200

Successful response

application/json

totalnumberOptional

The total balance amount

Example: 100.45

currencystringOptional

The balance currency

Example: eur

400

Bad request

application/json

404

Not found

application/json

get

/api/v2/partners/{partner_id}/balance

HTTPcURLJavaScriptPython

GET /api/v2/partners/{partner_id}/balance HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

[
  {
    "total": 1258.62,
    "currency": "usd"
  },
  {
    "total": 1,
    "currency": "eur"
  }
]

Retrieve the balance information for a specific client

get

This endpoint allows partners to retrieve the balance information for a particular client within the partner API. By providing the necessary authentication data, partner ID, and client ID, along with optional filters for the starting year, month, and application ID(s), you can obtain the corresponding balance data. The response will include details such as the client's balance and any associated financial information. Rate limits: This endpoint is subject to rate limits. A maximum of 5 requests in 30 seconds per client is allowed. Requests exceeding these limits will receive a 429 Too Many Requests response.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

client_idstringRequired

The ID of the client.

Example: exampleCL

partner_idstringRequired

The ID of the partner.

Example: examplePA

Query parameters

start_datenumber · floatOptional

The start date in UNIX Timestamp. Returned data will be equal to or newer than the specified date.

Default: 0

end_datenumber · floatOptional

The end date in UNIX Timestamp. Returned data will be equal to or older than the specified date.

Default: 4102358400

granularitystring · enumOptional

The granularity by which you would like to retrieve the analytics. Supported options: ['day', 'month]

Default: monthPossible values:

app_idsstring · nullableOptional

The ID(s) of the application(s). The returned data will be filtered by the specified application ID(s). Multiple IDs can be provided, separated by commas.

Default: nullExample: 214,231,241

Responses

200

Successful response

application/json

400

Wrong payload

application/json

404

Not found

application/json

429

Client error

application/json

get

/api/v2/partners/{partner_id}/clients/{client_id}/info/balance

HTTPcURLJavaScriptPython

GET /api/v2/partners/{partner_id}/clients/{client_id}/info/balance HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "balance": 100.45,
  "currency": "eur",
  "last_renewal": {
    "date": "2023-06-26T13:30:39Z",
    "amount": 200.12
  },
  "granularity": "month"
}

Retrieve pricing and call analytics usage for a specific channel. Check Meta documentation for more details.

get

This endpoint allows partners to retrieve detailed usage analytics and cost information for a specific channel within the partner API. By providing valid authentication, partner ID, client ID, and channel ID, along with optional filters such as date range, country codes, pricing types, and dimensions, partners can access a breakdown of usage data.

The response includes metrics such as message volume and cost across various pricing categories and types, organized by specified dimensions (e.g., country, pricing type). Rate limits: This endpoint is subject to rate limits. A maximum of 10 requests per hour per channel and 200 requests per hour per WABA is allowed. Requests exceeding these limits will receive a 429 Too Many Requests response.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

client_idstringRequired

The ID of the client.

Example: exampleCL

partner_idstringRequired

The ID of the partner.

Example: examplePA

channel_idstringRequired

The ID of the channel.

Example: exampleCH

Query parameters

start_dateinteger · timestampRequired

The start date in UNIX Timestamp. Returned data will be equal to or newer than the specified date.

Example: 1672531200

end_dateinteger · timestampRequired

The end date in UNIX Timestamp. Returned data will be equal to or older than the specified date.

Example: 1672531200

granularitystring · enumRequired

The granularity by which you would like to retrieve the analytics.

Possible values:

countriesstring[]Optional

The countries for which you would like to retrieve analytics. Provide a 2 letter country codes for the countries you would like to include. If not provided, usage data will be returned for all countries you have communicated with.

Example: ["us","gb","de"]

Responses

200

Successful response

application/json

400

Wrong payload

application/json

404

Not found

application/json

429

Client error

application/json

get

/api/v2/partners/{partner_id}/clients/{client_id}/channels/{channel_id}/info/usage

HTTPcURLJavaScriptPython

GET /api/v2/partners/{partner_id}/clients/{client_id}/channels/{channel_id}/info/usage?start_date=1672531200&end_date=1672531200&granularity=daily HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "18232736543210987",
  "currency": "USD",
  "pricing_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1749106800,
            "end": 1749193200,
            "country": "IN",
            "tier": "0:750000",
            "pricing_type": "REGULAR",
            "pricing_category": "AUTHENTICATION_INTERNATIONAL",
            "volume": 2,
            "cost": 4.6,
            "phone_number": "15550783881"
          },
          {
            "start": 1748934000,
            "end": 1749020400,
            "country": "US",
            "tier": "0:MAX",
            "pricing_type": "REGULAR",
            "pricing_category": "MARKETING",
            "volume": 1,
            "cost": 10,
            "phone_number": "15550783881"
          },
          {
            "start": 1748847600,
            "end": 1748934000,
            "country": "US",
            "pricing_type": "FREE_ENTRY_POINT",
            "pricing_category": "SERVICE",
            "volume": 6,
            "cost": 0,
            "phone_number": "15550783881"
          }
        ]
      }
    ]
  },
  "call_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1749106800,
            "end": 1749193200,
            "country": "IN",
            "count": 2,
            "cost": 4,
            "phone_number": "15550783881",
            "direction": "BUSINESS_INITIATED"
          }
        ]
      }
    ]
  }
}

Retrieve the balance information for a specific channel

get

This endpoint allows partners to retrieve the balance information for a particular channel within the partner API. By providing the necessary authentication data, partner ID, client ID, and channel ID, along with optional filters for the starting year, month, and application ID(s), you can obtain the corresponding balance data. The response will include details such as the channel's balance and any associated financial information.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

client_idstringRequired

The ID of the client.

Example: exampleCL

partner_idstringRequired

The ID of the partner.

Example: examplePA

channel_idstringRequired

The ID of the channel.

Example: exampleCH

Query parameters

start_datenumber · floatOptional

The start date in UNIX Timestamp. Returned data will be equal to or newer than the specified date.

Default: 0

end_datenumber · floatOptional

The end date in UNIX Timestamp. Returned data will be equal to or older than the specified date.

Default: 4102358400

granularitystring · enumOptional

The granularity by which you would like to retrieve the analytics. Supported options: ['day', 'month]

Default: monthPossible values:

Responses

200

Successful response

application/json

balancenumberOptional

The balance amount

Example: 100.45

currencystringOptional

The balance currency

Example: eur

estimated_template_costnumberOptionalDeprecated

[Deprecated]

ui_price_for_currency_and_client_countrynumberOptionalDeprecated

[Deprecated]

Example: 45.88

bi_price_for_currency_and_client_countrynumberOptionalDeprecated

[Deprecated]

Example: 65.88

granularitystringOptional

The time-based aggregation level - month or day

Example: month

400

Wrong payload

application/json

404

Not found

application/json

get

/api/v2/partners/{partner_id}/clients/{client_id}/channels/{channel_id}/info/balance

HTTPcURLJavaScriptPython

GET /api/v2/partners/{partner_id}/clients/{client_id}/channels/{channel_id}/info/balance HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "balance": 100.45,
  "currency": "eur",
  "last_renewal": {
    "date": "2023-06-26T13:30:39Z",
    "amount": 200.12
  },
  "granularity": "month"
}