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.
Unit pricing
With unit pricing, each unit costs a fixed amount. For example, $0.50 per API call.
{
...
"model_type": "unit",
"unit_config": {
"unit_amount": "0.50"
}
...
}
Tiered pricing
In tiered pricing, the cost of a given unit depends on the tier range that it falls into, where each tier range is defined by an upper and lower bound. For example, the first ten units may cost $0.50 each and all units thereafter may cost $0.10 each. The first_unit is exclusive while the last_unit is inclusive.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 0,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 10,
"last_unit": null,
"unit_amount": "0.10"
}
]
}
...
Bulk pricing
Bulk pricing applies when the number of units determine the cost of all units. For example, if you’ve bought less than 10 units, they may each be $0.50 for a total of $5.00. Once you’ve bought more than 10 units, all units may now be priced at $0.40 (i.e. 101 units total would be $40.40).
{
...
"model_type": "bulk",
"bulk_config": {
"tiers": [
{
"maximum_units": 10,
"unit_amount": "0.50"
},
{
"maximum_units": 1000,
"unit_amount": "0.40"
}
]
}
...
}
Package pricing
Package pricing defines the size or granularity of a unit for billing purposes. For example, if the package size is set to 10, then 4 units will be billed as 10 and 11 units will be billed at 20.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
Dimensional pricing
Dimensional pricing defines a set of unit prices in a one , or many dimensional matrix. dimensions defines the event property values evaluated in this pricing model.
For comprehensive guidance on dimensional pricing, see the dimensional pricing guide.
{
"model_type": "unit",
"unit_config": {
"unit_amount": "0.50"
}
...
"dimensional_price_group_config": {
"external_dimensional_price_group_id": "compute",
"dimension_values": ["region", "instance_type", "cloud_provider"]
}
License pricing
License pricing allows you to model generic entitlements in Orb, where usage can be attributed to a unique license for a billing period. The most common application of licenses is to model seat-based pricing in Orb, but can be extended to represent anything from bots, agents, workflows, machines. etc
Each license can include its own allocation of credits to handle proper billing, fair-usage enforcement, reporting and alerting per entitlement, while still participating in the shared subscription credit pool and standard account-level overage billing.
For comprehensive guidance on license pricing, see the license management docs.
{
...
"model_type": "unit",
"unit_config": {
"unit_amount": "10.00"
},
"license_type_id": "<unique id for the license type>",
...
}
Matrix pricing
Matrix pricing defines a set of unit prices in a one or two-dimensional matrix. dimensions defines the two event property values evaluated in this pricing model. In a one-dimensional matrix, the second value is null. Every configuration has a list of matrix_values which give the unit prices for specified property values. In a one-dimensional matrix, the matrix values will have dimension_values where the second value of the pair is null. If an event does not match any of the dimension values in the matrix, it will resort to the default_unit_amount. Importantly, the values for the dimension properties sent in the event should always be sent as a string i.e with quotes around them. For example, the pricing is that any call will be $3.00, but if the call is made in the alpha or west region, it will be $2.00.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
Billing timing and cadence
Every price has two timing-related configurations that control when charges appear on invoices:
Billing mode
The billing mode determines when within a billing period the charge is calculated:
| Billing mode | When charged | Use for |
|---|
| In-arrears | End of the billing period | Usage-based charges, metered fees |
| In-advance | Start of the billing period | Platform fees, seat licenses, subscriptions |
Credit eligibility: Prepaid credits can only be applied to in-arrears charges. In-advance fees are charged immediately and do not draw from prepaid credit balances.
Cadence
The cadence determines the length of the billing period:
| Cadence | Billing period | Typical use |
|---|
| Monthly | Calendar month | Standard billing |
| Quarterly | 3 months | Enterprise commitments |
| Semi-annual | 6 months | Large contracts |
| Annual | 12 months | Annual subscriptions |
| One-time | Single charge | Setup fees, credits |
| Custom | Specified in days | Non-standard terms |
Fixed fees
Fixed fees are prices that are applied independent of usage quantities, and follow unit pricing. They also have an additional parameter fixed_price_quantity. If the Price represents a fixed cost, this represents the quantity of units applied.
{
...
"id": "price_id",
"model_type": "unit",
"unit_config": {
"unit_amount": "2.00"
},
"fixed_price_quantity": 3.0
...
}
