billing

Get the effective price for a product

Changed on

Returns the effective unit price, tax, and gross price for a product after organization- and plan-specific pricing. Provide exactly one of product_id or product_slug. You can also provide pricing dimensions and a currency. Pass plan_id to price under a published self-serve plan in place of your current plan; organization-specific rates still take precedence. The currency defaults to the organization's billing currency; if necessary, the price is converted from the product's base currency. Requires a delegated user OAuth token with org:billing:read; workspace and organization master API keys are refused with 403.

get/v1/organization/billing/prices/resolve

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/organization/billing/prices/resolve
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Query parameters

product_idstring
Example:prd_01krdgeqcxet5s7t44vh8rt9mg

Product ID to price. Provide exactly one of product_id or product_slug.

product_slugstring

Product slug to price. Provide exactly one of product_id or product_slug.

plan_idstring
Example:prd_01krdgeqcxet5s7t44vh8rt9mg

Published self-serve plan to price under in place of your current plan. Returns 404 if the plan is not an active self-serve plan.

dimensionsobject

Key-value pairs that refine attribute-based pricing, such as destination country or sender type. For example, dimensions[country_code]=US.

currencystring

Three-letter ISO currency code. Defaults to your organization's billing currency.

Headers

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The resolved price.

tax_ratestring required

The tax rate applied to this price for your organization, as a decimal (for example 0.21 for 21%). 0 if your organization is tax-exempt or no tax applies.

billing_unit_sizeinteger required

Number of units that form one chargeable block. Overage usage is ceiling-rounded to the nearest multiple of this value before the unit price is applied. A value of 1 charges per individual unit.

incrementstring nullable

The billing rounding window for time-based products, expressed as {initial_seconds}/{continuation_seconds}. For example, 60/60 means each unit covers 60 seconds. null for per-unit products.

dimensionsobject required

Pricing dimensions that determined this price (for example, country_code, sender_type).

namestring required

Display name of the product this price was resolved for.

external_descriptionstring nullable

Customer-facing description of the product this price was resolved for, when set.

pricing_model'plan' | 'metered' | 'rate_card' | 'unit_subscription' | 'custom' | 'counter' required

How this product is priced.

  • plan: it comes with the organization's subscribed plan, with usage tracked against that plan's included allowance.
  • metered: it is billed per unit beyond any included allowance.
  • rate_card: the per-unit price varies by attributes of the usage, such as destination, instead of being flat.
  • unit_subscription: it is a standalone add-on billed as its own recurring subscription, independent of the plan.
  • custom: a pricing arrangement that does not fit the other models.
  • counter: usage is recorded without enforcing a spending cap or blocking requests.
billing_interval'day' | 'month' | 'year'

The recurring interval one subscription charge covers.

billing_interval_countinteger

Compatibility alias for intervals_per_charge. Only present when pricing_model is unit_subscription, or plan with configured recurring terms. Omitted for other pricing models and plans without configured terms.

intervals_per_chargeinteger

Number of complete pricing intervals bought by each recurring charge. Renewal duration is pricing_interval.count multiplied by this value. Present alongside pricing_interval for unit_subscription products and plans with configured recurring terms; omitted otherwise.

Example response

{
  "unit_price": {
    "amount": "0.00995",
    "currency_code": "EUR"
  },
  "tax_rate": "0.21",
  "tax_amount": {
    "amount": "0.00995",
    "currency_code": "EUR"
  },
  "gross_price": {
    "amount": "0.00995",
    "currency_code": "EUR"
  },
  "billing_unit_size": 1000,
  "increment": "60/60",
  "dimensions": {
    "country_code": "US"
  },
  "name": "10DLC Brand Registration",
  "pricing_model": "rate_card",
  "billing_interval": "month",
  "billing_interval_count": 1,
  "pricing_interval": {
    "unit": "month",
    "count": 3
  },
  "intervals_per_charge": 1
}

Changes