API Documentation
Alert
Customer
- GETList customers
- POSTCreate customer
- GETFetch customer by external ID
- PUTUpdate customer by external ID
- GETFetch customer costs by external ID
- POSTUpdate payment methods from payment provider
- GETFetch customer
- PUTUpdate customer
- DELDelete customer
- GETList balance transactions
- POSTCreate customer balance transaction
- GETFetch customer costs
- POSTUpdate payment methods from payment provider
Credit
- GETFetch customer credit balance by external customer id
- GETFetch customer credits ledger by external ID
- POSTCreate ledger entry by external ID
- GETList top-ups by external ID
- POSTCreate top-up by external ID
- DELDeactivate top-up by external ID
- GETFetch customer credit balance
- GETFetch customer credits ledger
- POSTCreate ledger entry
- GETList top-ups
- POSTCreate top-up
- DELDeactivate top-up
Dimensional Price Group
Event
Invoice
Availability
Plan
Price
Subscription
- GETList subscriptions
- POSTCreate subscription
- GETFetch subscription
- PUTUpdate subscription
- POSTCancel subscription
- GETFetch subscription costs
- GETFetch subscription schedule
- POSTSchedule plan change
- POSTTrigger phase
- POSTUnschedule subscription cancellation
- POSTUnschedule fixed fee quantity updates
- POSTUnschedule plan change
- POSTUpdate price quantity
- POSTUpdate trial for subscription
- GETFetch subscription usage
Price interval
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).
curl --request GET \
--url https://api.withorb.com/v1/subscriptions/{subscription_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
API Keys can be issued in the Orb's web application.
Path Parameters
Query Parameters
Costs returned are inclusive of timeframe_start.
Costs returned are exclusive of timeframe_end.
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.
periodic, cumulative The currency or custom pricing unit to use.
Response
Total costs for the timeframe, excluding any minimums and discounts.
Total costs for the timeframe, including any minimums and discounts.
Price's contributions for the timeframe, excluding any minimums and discounts.
Price's contributions for the timeframe, including minimums and discounts.
The price object
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.
usage_price, fixed_price unit one_time, monthly, quarterly, semi_annual, annual, custom percentage List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Only available if discount_type is percentage. This is a number between 0 and 1.
0 < x < 1Rate per unit of usage
The price the cost is associated with
The price's quantity for the timeframe
Was this page helpful?
curl --request GET \
--url https://api.withorb.com/v1/subscriptions/{subscription_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>"
}
]
}
]
}