API documentation
Alert
Credit
- GETFetch credit block
- DELDelete credit block
- 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
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
Dimensional Price Group
Event
Invoice
Availability
Plan
- GETList plans
- POSTCreate plan
- GETFetch plan by external ID
- PUTUpdate plan by external ID
- POSTSet plan version as default by external ID
- POSTCreate plan version by external ID
- GETFetch plan version by external ID
- GETFetch plan
- PUTUpdate plan by id
- GETList migrations
- GETFetch migration
- POSTCancel migration
- POSTSet plan version as default
- POSTCreate plan version
- GETFetch plan version
Price
Subscription Change
Subscription
- GETList subscriptions
- POSTCreate subscription
- GETFetch subscription
- PUTUpdate subscription
- POSTCancel subscription
- GETFetch subscription costs
- POSTRedeem Coupon
- 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
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": [
{
"subtotal": "<string>",
"total": "<string>",
"price": {
"model_type": "unit",
"unit_config": {
"unit_amount": "<string>",
"prorated": false
},
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"replaces_price_id": "<string>",
"price_type": "usage_price",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_mode": "in_advance",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"conversion_rate_config": {
"conversion_rate_type": "unit",
"unit_config": {
"unit_amount": "<string>"
}
},
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true,
"custom_expiration": {
"duration": 123,
"duration_unit": "day"
},
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"composite_price_filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"discount": {
"discount_type": "percentage",
"percentage_discount": 0.5,
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>"
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"maximum_amount": "<string>",
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
}
},
"price_id": "<string>",
"quantity": 123
}
]
}
]
}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": [
{
"subtotal": "<string>",
"total": "<string>",
"price": {
"model_type": "unit",
"unit_config": {
"unit_amount": "<string>",
"prorated": false
},
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"replaces_price_id": "<string>",
"price_type": "usage_price",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_mode": "in_advance",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"conversion_rate_config": {
"conversion_rate_type": "unit",
"unit_config": {
"unit_amount": "<string>"
}
},
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true,
"custom_expiration": {
"duration": 123,
"duration_unit": "day"
},
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"composite_price_filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"discount": {
"discount_type": "percentage",
"percentage_discount": 0.5,
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>"
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"maximum_amount": "<string>",
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
}
},
"price_id": "<string>",
"quantity": 123
}
]
}
]
}Authorizations
API Keys can be issued in the Orb's web application.
Path Parameters
Query Parameters
Costs returned are inclusive of timeframe_start.
"2022-02-01T05:00:00Z"
Costs returned are exclusive of timeframe_end.
"2022-03-01T05:00:00Z"
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
OK
Show child attributes
Show child attributes
Total costs for the timeframe, excluding any minimums and discounts.
Total costs for the timeframe, including any minimums and discounts.
Show child attributes
Show child attributes
Price's contributions for the timeframe, excluding any minimums and discounts.
Price's contributions for the timeframe, including minimums and discounts.
The price object
- UnitPrice
- TieredPrice
- BulkPrice
- BulkWithFiltersPrice
- PackagePrice
- MatrixPrice
- ThresholdTotalAmountPrice
- TieredPackagePrice
- TieredWithMinimumPrice
- GroupedTieredPrice
- TieredPackageWithMinimumPrice
- PackageWithAllocationPrice
- UnitWithPercentPrice
- MatrixWithAllocationPrice
- TieredWithProrationPrice
- UnitWithProrationPrice
- GroupedAllocationPrice
- BulkWithProrationPrice
- GroupedWithProratedMinimumPrice
- GroupedWithMeteredMinimumPrice
- GroupedWithMinMaxThresholdsPrice
- MatrixWithDisplayNamePrice
- GroupedTieredPackagePrice
- MaxGroupTieredPackagePrice
- ScalableMatrixWithUnitPricingPrice
- ScalableMatrixWithTieredPricingPrice
- CumulativeGroupedBulkPrice
- CumulativeGroupedAllocationPrice
- MinimumCompositePrice
- PercentCompositePrice
- EventOutputPrice
Show child attributes
Show child attributes
The pricing model type
unit 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.
Show child attributes
Show child attributes
The price id this price replaces. This price will take the place of the replaced price in plan version migrations.
usage_price, fixed_price, composite_price one_time, monthly, quarterly, semi_annual, annual, custom in_advance, in_arrear - UnitConversionRateConfig
- TieredConversionRateConfig
Show child attributes
Show child attributes
unit Show child attributes
Show child attributes
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
- PercentageDiscount
- TrialDiscount
- UsageDiscount
- AmountDiscount
Show child attributes
Show child attributes
percentage Only available if discount_type is percentage. This is a number between 0 and 1.
0 <= x <= 1List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]The filters that determine which prices to apply this discount to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
Show child attributes
Show child attributes
Minimum amount applied
The filters that determine which prices to apply this minimum to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
Show child attributes
Show child attributes
Maximum amount applied
The filters that determine which prices to apply this maximum to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
The price the cost is associated with
The price's quantity for the timeframe
Was this page helpful?