Subscription

Fetch subscription costs

This endpoint is used to fetch a day-by-day snapshot of a subscription’s costs in Orb, calculated by applying pricing information to the underlying usage (see the subscription usage endpoint to fetch usage per metric, in usage units rather than a currency).

The semantics of this endpoint exactly mirror those of fetching a customer’s costs. Use this endpoint to limit your analysis of costs to a specific subscription for the customer (e.g. to de-aggregate costs when a customer’s subscription has started and stopped on the same day).

GET

subscriptions

{subscription_id}

costs

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Path Parameters

subscription_id

string

required

Query Parameters

timeframe_start

string | null

Costs returned are inclusive of timeframe_start.

timeframe_end

string | null

Costs returned are exclusive of timeframe_end.

view_mode

enum<string> | null

Controls whether Orb returns cumulative costs since the start of the billing period, or incremental day-by-day costs. If your customer has minimums or discounts, it's strongly recommended that you use the default cumulative behavior.

Available options:

periodic,

cumulative

currency

string | null

The currency or custom pricing unit to use.

Response

200 - application/json

data

object[]

required

data.per_price_costs

object[]

required

data.per_price_costs.price

object

required

The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill.

Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present.

For more on the types of prices, see the core concepts documentation

data.per_price_costs.price.billable_metric

object | null

required

data.per_price_costs.price.billing_cycle_configuration

object

required

data.per_price_costs.price.cadence

enum<string>

required

Available options:

one_time,

monthly,

quarterly,

semi_annual,

annual,

custom

data.per_price_costs.price.conversion_rate

number | null

required

data.per_price_costs.price.created_at

string

required

data.per_price_costs.price.credit_allocation

object | null

required

data.per_price_costs.price.currency

string

required

data.per_price_costs.price.discount

object | null

required

data.per_price_costs.price.external_price_id

string | null

required

data.per_price_costs.price.fixed_price_quantity

number | null

required

data.per_price_costs.price.id

string

required

data.per_price_costs.price.invoicing_cycle_configuration

object | null

required

data.per_price_costs.price.item

object

required

data.per_price_costs.price.maximum

object | null

required

data.per_price_costs.price.maximum_amount

string | null

required

data.per_price_costs.price.metadata

object

required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

data.per_price_costs.price.minimum

object | null

required

data.per_price_costs.price.minimum_amount

string | null

required

data.per_price_costs.price.model_type

enum<string>

required

Available options:

unit

data.per_price_costs.price.name

string

required

data.per_price_costs.price.plan_phase_order

integer | null

required

data.per_price_costs.price.price_type

enum<string>

required

Available options:

usage_price,

fixed_price

data.per_price_costs.price.unit_config

object

required

data.per_price_costs.subtotal

string

required

Price's contributions for the timeframe, excluding any minimums and discounts.

data.per_price_costs.total

string

required

Price's contributions for the timeframe, including minimums and discounts.

data.per_price_costs.quantity

number | null

The price's quantity for the timeframe

data.subtotal

string

required

Total costs for the timeframe, excluding any minimums and discounts.

data.timeframe_end

string

required

data.timeframe_start

string

required

data.total

string

required

Total costs for the timeframe, including any minimums and discounts.

Was this page helpful?

Cancel subscription Fetch subscription schedule

API Documentation

Alert

Coupon

Credit note

Customer

Credit

Dimensional Price Group

Event

Invoice

Item

Metric

Availability

Plan

Price

Subscription

Price interval

Fetch subscription costs

Authorizations

Path Parameters

Query Parameters

Response