Customer

Fetch customer costs by external ID

This endpoint is used to fetch a day-by-day snapshot of a customer’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).

This endpoint can be leveraged for internal tooling and to provide a more transparent billing experience for your end users:

Understand the cost breakdown per line item historically and in real-time for the current billing period.
Provide customer visibility into how different services are contributing to the overall invoice with a per-day timeseries (as compared to the upcoming invoice resource, which represents a snapshot for the current period).
Assess how minimums and discounts affect your customers by teasing apart costs directly as a result of usage, as opposed to minimums and discounts at the plan and price level.
Gain insight into key customer health metrics, such as the percent utilization of the minimum committed spend.

Fetching subscriptions

By default, this endpoint fetches the currently active subscription for the customer, and returns cost information for the subscription’s current billing period, broken down by each participating price. If there are no currently active subscriptions, this will instead default to the most recently active subscription or return an empty series if none are found. For example, if your plan charges for compute hours, job runs, and data syncs, then this endpoint would provide a daily breakdown of your customer’s cost for each of those axes.

If timeframe bounds are specified, Orb fetches all subscriptions that were active in that timeframe. If two subscriptions overlap on a single day, costs from each price will be summed, and prices for both subscriptions will be included in the breakdown.

Prepaid plans

For plans that include prices which deduct credits rather than accrue in-arrears charges in a billable currency, this endpoint will return the total deduction amount, in credits, for the specified timeframe.

Cumulative subtotals and totals

Since the subtotal and total must factor in any billing-period level discounts and minimums, it’s most meaningful to consider costs relative to the start of the subscription’s billing period. As a result, by default this endpoint returns cumulative totals since the beginning of the billing period. In particular, the timeframe_start of a returned timeframe window is always the beginning of the billing period and timeframe_end is incremented one day at a time to build the result.

A customer that uses a few API calls a day but has a minimum commitment might exhibit the following pattern for their subtotal and total in the first few days of the month. Here, we assume that each API call is $2.50, the customer's plan has a monthly minimum of$ 50 for this price, and that the subscription’s billing period bounds are aligned to the first of the month:

timeframe_start	timeframe_end	Cumulative usage	Subtotal	Total (incl. commitment)
2023-02-01	2023-02-02	9	$22.50	$50.00
2023-02-01	2023-02-03	19	$47.50	$50.00
2023-02-01	2023-02-04	20	$50.00	$50.00
2023-02-01	2023-02-05	28	$70.00	$70.00
2023-02-01	2023-02-06	36	$90.00	$90.00

Periodic values

When the query parameter view_mode=periodic is specified, Orb will return an incremental day-by-day view of costs. In this case, there will always be a one-day difference between timeframe_start and timeframe_end for the timeframes returned. This is a transform on top of the cumulative costs, calculated by taking the difference of each timeframe with the last. Note that in the above example, the Total value would be 0 for the second two data points, since the minimum commitment has not yet been hit and each day is not contributing anything to the total cost.

Timeframe bounds

For an active subscription, both timeframes should be specified in the request. If a subscription starts or ends within the timeframe, the response will only include windows where the subscription is active. If a subscription has ended, no timeframe bounds need to be specified and the response will default to the billing period when the subscription was last active.

As noted above, timeframe_start for a given cumulative datapoint is always the beginning of the billing period, and timeframe_end is incremented one day at a time to construct the response. When a timeframe is passed in that is not aligned to the current subscription’s billing period, the response will contain cumulative totals from multiple billing periods.

Suppose the queried customer has a subscription aligned to the 15th of every month. If this endpoint is queried with the date range 2023-06-01 - 2023-07-01, the first data point will represent about half a billing period’s worth of costs, accounting for accruals from the start of the billing period and inclusive of the first day of the timeframe (timeframe_start = 2023-05-15 00:00:00, timeframe_end = 2023-06-02 00:00:00)

datapoint index	timeframe_start	timeframe_end
0	2023-05-15	2023-06-02
1	2023-05-15	2023-06-03
2	…	…
3	2023-05-15	2023-06-14
4	2023-06-15	2023-06-16
5	2023-06-15	2023-06-17
6	…	…
7	2023-06-15	2023-07-01

You can see this sliced timeframe visualized here.

Matrix prices

When a price uses matrix pricing, it’s important to view costs grouped by those matrix dimensions. Orb will return price_groups with the grouping_key and secondary_grouping_key based on the matrix price definition, for each grouping_value and secondary_grouping_value available.

GET

customers

external_customer_id

{external_customer_id}

costs

curl --request GET \
  --url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/costs \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "subtotal": "<string>",
      "total": "<string>",
      "timeframe_start": "2023-11-07T05:31:56Z",
      "timeframe_end": "2023-11-07T05:31:56Z",
      "per_price_costs": [
        {
          "quantity": 123,
          "subtotal": "<string>",
          "total": "<string>",
          "price": {
            "metadata": {},
            "id": "<string>",
            "name": "<string>",
            "external_price_id": "<string>",
            "price_type": "usage_price",
            "model_type": "unit",
            "created_at": "2023-11-07T05:31:56Z",
            "cadence": "one_time",
            "billing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "invoicing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "billable_metric": {
              "id": "<string>"
            },
            "dimensional_price_configuration": {
              "dimensional_price_group_id": "<string>",
              "dimension_values": [
                "<string>"
              ]
            },
            "fixed_price_quantity": 123,
            "plan_phase_order": 123,
            "currency": "<string>",
            "conversion_rate": 123,
            "item": {
              "id": "<string>",
              "name": "<string>"
            },
            "credit_allocation": {
              "currency": "<string>",
              "allows_rollover": true
            },
            "discount": {
              "discount_type": "percentage",
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "reason": "<string>",
              "percentage_discount": 0.15
            },
            "minimum": {
              "minimum_amount": "<string>",
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "minimum_amount": "<string>",
            "maximum": {
              "maximum_amount": "<string>",
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "maximum_amount": "<string>",
            "unit_config": {
              "unit_amount": "<string>"
            }
          },
          "price_id": "<string>"
        }
      ]
    }
  ]
}

Authorizations

Authorization

string

header

required

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

Path Parameters

external_customer_id

string | null

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.subtotal

string

required

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

data.total

string

required

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

data.timeframe_start

string

required

data.timeframe_end

string

required

data.per_price_costs

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.price

object

required

The price object

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.id

string

required

data.per_price_costs.price.name

string

required

data.per_price_costs.price.external_price_id

string | null

required

data.per_price_costs.price.price_type

enum<string>

required

Available options:

usage_price,

fixed_price

data.per_price_costs.price.model_type

enum<string>

required

Available options:

unit

data.per_price_costs.price.created_at

string

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.billing_cycle_configuration

object

required

data.per_price_costs.price.invoicing_cycle_configuration

object | null

required

data.per_price_costs.price.billable_metric

object | null

required

data.per_price_costs.price.fixed_price_quantity

number | null

required

data.per_price_costs.price.plan_phase_order

integer | null

required

data.per_price_costs.price.currency

string

required

data.per_price_costs.price.conversion_rate

number | null

required

data.per_price_costs.price.item

object

required

data.per_price_costs.price.credit_allocation

object | null

required

data.per_price_costs.price.discount

object | null

required

data.per_price_costs.price.minimum

object | null

required

data.per_price_costs.price.minimum_amount

string | null

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.unit_config

object

required

data.per_price_costs.price.dimensional_price_configuration

object | null

data.per_price_costs.price_id

string

required

The price the cost is associated with

data.per_price_costs.quantity

number | null

The price's quantity for the timeframe

Was this page helpful?

Update customer by external ID Update payment methods from payment provider

curl --request GET \
  --url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/costs \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "subtotal": "<string>",
      "total": "<string>",
      "timeframe_start": "2023-11-07T05:31:56Z",
      "timeframe_end": "2023-11-07T05:31:56Z",
      "per_price_costs": [
        {
          "quantity": 123,
          "subtotal": "<string>",
          "total": "<string>",
          "price": {
            "metadata": {},
            "id": "<string>",
            "name": "<string>",
            "external_price_id": "<string>",
            "price_type": "usage_price",
            "model_type": "unit",
            "created_at": "2023-11-07T05:31:56Z",
            "cadence": "one_time",
            "billing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "invoicing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "billable_metric": {
              "id": "<string>"
            },
            "dimensional_price_configuration": {
              "dimensional_price_group_id": "<string>",
              "dimension_values": [
                "<string>"
              ]
            },
            "fixed_price_quantity": 123,
            "plan_phase_order": 123,
            "currency": "<string>",
            "conversion_rate": 123,
            "item": {
              "id": "<string>",
              "name": "<string>"
            },
            "credit_allocation": {
              "currency": "<string>",
              "allows_rollover": true
            },
            "discount": {
              "discount_type": "percentage",
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "reason": "<string>",
              "percentage_discount": 0.15
            },
            "minimum": {
              "minimum_amount": "<string>",
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "minimum_amount": "<string>",
            "maximum": {
              "maximum_amount": "<string>",
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "maximum_amount": "<string>",
            "unit_config": {
              "unit_amount": "<string>"
            }
          },
          "price_id": "<string>"
        }
      ]
    }
  ]
}

API Documentation

Alert

Coupon

Credit note

Customer

Credit

Dimensional Price Group

Event

Invoice

Item

Metric

Availability

Plan

Price

Subscription

Price interval

Fetch customer costs by external ID

Fetching subscriptions

Prepaid plans

Cumulative subtotals and totals

Periodic values

Timeframe bounds

Matrix prices

Authorizations

Path Parameters

Query Parameters

Response