Billing Usage API overview

OpenAPI Spec

Machine-readable spec for the Billing Usage API: beta/categories/billing_usage.json

Before you begin

Check out our general API overview to make sure you're ready to get started with specific endpoints.

🚧

The Billing Usage API is in beta. You must pin a beta revision (for example, revision: 2026-07-15.pre) to call these endpoints. Beta endpoints may change before they reach general availability.

The Billing Usage API lets you read an account's current-period metered usage against its plan caps. For each product an account is billed for, the API reports how much has been consumed so far this period (usage_used), the plan limit (usage_max), the unit those values are denominated in, and the billing period the numbers cover. These are the same figures that populate the usage bars on the account's billing overview page.

Use cases

Here are example use cases supported by the Billing Usage API:

• Build an internal dashboard that tracks email sends and active profiles against plan limits across the billing period.
• Alert your team when consumption for a usage type approaches its cap.
• Retrieve a single usage type's current consumption to display in a customer-facing app.

Required scopes

To use Billing Usage API endpoints, your API key or OAuth app needs the following scope:

• usage:read - required to read billing usage.

A key without usage:read receives a 403 response. See Troubleshooting.

Data model

The billing-usage resource represents one usage type's current-period consumption and cap. The resource id is the usage type key (for example, email_sends) - there is no separate opaque identifier.

Each billing-usage object has the following attributes:

• usage_used

  Amount consumed against this usage type in the current period, rounded to 4 decimal places.

• usage_max

  Maximum usage allowed for this usage type on the current plan.

• unit

  The unit usage_used and usage_max are denominated in. One of messages, profiles, credits, USD, resolutions, conversations, or orders.

• period_start

  Start of the current billing period for this usage type, in UTC.

• period_end

  Exclusive end of the current billing period for this usage type, in UTC. Usage is counted up to but not including this instant.

• as_of

  When this usage_used value was last read, in UTC.

Usage types

An account only returns the usage types for the products it is billed for. A usage type appears once the corresponding product is released for the account and disappears when that plan is canceled. The following usage types are available:

📘

active_profiles is not updated in real time - it refreshes about twice a day. Use the as_of attribute to see when a value was last read.

List billing usage

Use List Billing Usage to retrieve every usage type the account is billed for.

curl --request GET \
  --url 'https://a.klaviyo.com/api/billing-usage' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/json' \
  --header 'revision: 2026-07-15.pre'

{
    "data": [
        {
            "type": "billing-usage",
            "id": "active_profiles",
            "attributes": {
                "usage_used": 12450.0,
                "usage_max": 25000,
                "unit": "profiles",
                "period_start": "2026-07-01T04:00:00+00:00",
                "period_end": "2026-08-01T04:00:00+00:00",
                "as_of": "2026-07-09T18:30:04.769339+00:00"
            },
            "links": {
                "self": "https://a.klaviyo.com/api/billing-usage/active_profiles/"
            }
        },
        {
            "type": "billing-usage",
            "id": "email_sends",
            "attributes": {
                "usage_used": 84210.0,
                "usage_max": 250000,
                "unit": "messages",
                "period_start": "2026-07-01T04:00:00+00:00",
                "period_end": "2026-08-01T04:00:00+00:00",
                "as_of": "2026-07-09T18:30:04.769364+00:00"
            },
            "links": {
                "self": "https://a.klaviyo.com/api/billing-usage/email_sends/"
            }
        },
        {
            "type": "billing-usage",
            "id": "ai_credits",
            "attributes": {
                "usage_used": 320.0,
                "usage_max": 10000,
                "unit": "credits",
                "period_start": "2026-07-01T04:00:00+00:00",
                "period_end": "2026-08-01T04:00:00+00:00",
                "as_of": "2026-07-09T18:30:04.769400+00:00"
            },
            "links": {
                "self": "https://a.klaviyo.com/api/billing-usage/ai_credits/"
            }
        }
    ],
    "links": {
        "self": "https://a.klaviyo.com/api/billing-usage/"
    }
}

Get billing usage

Use Get Billing Usage to retrieve a single usage type by its id.

curl --request GET \
  --url 'https://a.klaviyo.com/api/billing-usage/email_sends' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/json' \
  --header 'revision: 2026-07-15.pre'

{
    "data": {
        "type": "billing-usage",
        "id": "email_sends",
        "attributes": {
            "usage_used": 84210.0,
            "usage_max": 250000,
            "unit": "messages",
            "period_start": "2026-07-01T04:00:00+00:00",
            "period_end": "2026-08-01T04:00:00+00:00",
            "as_of": "2026-07-09T18:30:04.769364+00:00"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/billing-usage/email_sends/"
        }
    },
    "links": {
        "self": "https://a.klaviyo.com/api/billing-usage/email_sends"
    }
}

If you request a usage type the account is not currently billed for - for example after the corresponding plan has been canceled - the endpoint returns 404:

{
    "errors": [
        {
            "id": "c7f65136-f406-4b68-945f-84cc274d8437",
            "status": 404,
            "code": "not_found",
            "title": "Not found.",
            "detail": "No billing usage found for usage type 'email_sends' on this account.",
            "source": {
                "pointer": "/data/"
            }
        }
    ]
}

Querying billing usage

id is the only filterable field on this resource. Combine filters and sparse fieldsets to narrow both which usage types and which attributes are returned.

Usage type ids in a filter that the account is not billed for are silently skipped, and only the valid ids are returned. For example, filtering on any(id,["aa_active_profiles","active_profiles"]) for an account without advanced analytics returns only active_profiles.

Account families

For accounts in an account family, billing usage is reported at the family level. Both the parent and each child account return the same values:

• usage_used for each usage type is the total across the whole account family.
• usage_max, period_start, and period_end match the parent's exactly.

A request to a child account returns the same figures as the parent - the response reflects family-wide usage, not the individual account's contribution.

Rate limits

Billing Usage API endpoints use the MEDIUM rate limit tier: 10 requests/second burst and 150 requests/minute steady. See rate limits for more information.

Troubleshooting

Additional resources

• List Billing Usage
• Get Billing Usage
• Filtering
• Sparse fieldsets
• Rate limits, status codes, and errors