Create subscription
A subscription represents the purchase of a plan by a customer. The customer is identified by either the customer_id
or the external_customer_id
, and exactly one of these fields must be provided.
By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition.
The default configuration for subscriptions in Orb is In-advance billing and Beginning of month alignment (see Subscription for more details).
In order to change the alignment behavior, Orb also supports billing subscriptions on the day of the month they are
created. If align_billing_with_subscription_start_date = true
is specified, subscriptions have billing cycles that are
aligned with their start_date
. For example, a subscription that begins on January 15th will have a billing cycle from
January 15th to February 15th. Every subsequent billing cycle will continue to start and invoice on the 15th.
If the "day" value is greater than the number of days in the month, the next billing cycle will start at the end of the month. For example, if the start_date is January 31st, the next billing cycle will start on February 28th.
If a customer was created with a currency, Orb only allows subscribing the customer to a plan with a matching
invoicing_currency
. If the customer does not have a currency set, on subscription creation, we set the customer's
currency to be the invoicing_currency
of the plan.
Price overrides
Price overrides are used to update some or all prices in a plan for the specific subscription being created. This is useful when a new customer has negotiated one or more different prices for a specific plan than the plan's default prices. Any type of price can be overridden, if the correct data is provided. The billable metric, cadence, type, and name of a price can not be overridden.
To override prices, provide a list of objects with the key price_overrides
. The price object in the list of overrides
is expected to contain the existing price id, the model_type
and config value in the format below. The specific
numerical values can be updated, but the config value and model_type
must match the existing price that is being
overridden
Request format for price overrides
Orb supports a few different pricing models out of the box. 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.
{
...
"id": "price_id",
"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. Tiered prices can be overridden with a new number of tiers or new values for first_unit
, last_unit
,
or unit_amount
.
{
...
"id": "price_id",
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit":"1",
"last_unit": "11",
"unit_amount": "0.50"
},
{
"first_unit": "11",
"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). Bulk prices can be overridden with a new number of tiers or new
values for maximum_units
, or unit_amount
.
{
...
"id": "price_id",
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"id": "price_id",
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"id": "price_id"
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_event_cap": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper and lower bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
{
...
"id": "price_id"
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"minimum_amount": "0.00",
"maximum_amount": "1000000.00",
"bps": 125,
"per_event_cap": "19.00"
},
{
"minimum_amount":"1000000.00",
"maximum_amount": null,
"bps": 115,
"per_event_cap": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
{
...
"id": "price_id"
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0.00",
"maximum_amount": "1000000.00",
"bps": 125,
"per_event_cap": "19.00"
},
{
"minimum_amount":"1000000",
"maximum_amount": null,
"bps": 115,
"per_event_cap": "4.00"
}
]
}
...
}
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
.
{
...
"model_type": "matrix",
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
Fixed fees
Fixed fees follow unit pricing, and also have an additional parameter fixed_price_quantity
that indicates how many of
a fixed fee that should be applied for a subscription. This parameter defaults to 1.
{
...
"id": "price_id",
"model_type": "unit",
"unit_config": {
"unit_amount": "2.00"
},
"fixed_price_quantity": 3.0
...
}
Maximums and Minimums
Minimums and maximums, much like price overrides, can be useful when a new customer has negotiated a new or different minimum or maximum spend cap than the default for a given price. If one exists for a price and null is provided for the minimum/maximum override on creation, then there will be no minimum/maximum on the new subscription. If no value is provided, then the default price maximum or minimum is used.
To add a minimum for a specific price, add minimum_amount
to the specific price in the price_overrides
object.
To add a maximum for a specific price, add maximum_amount
to the specific price in the price_overrides
object.
Minimum override example
Price minimum override example:
{
...
"id": "price_id",
"model_type": "unit",
"unit_config": {
"unit_amount": "0.50"
},
"minimum_amount": "100.00"
...
}
Removing an existing minimum example
{
...
"id": "price_id",
"model_type": "unit",
"unit_config": {
"unit_amount": "0.50"
},
"minimum_amount": null
...
}
Discounts
Discounts, like price overrides, can be useful when a new customer has negotiated a new or different discount than the default for a price. A single price price can have at most one discount. If a discount exists for a price and a null discount is provided on creation, then there will be no discount on the new subscription.
To add a discount for a specific price, add discount
to the price in the price_overrides
object.
Discount should be a dictionary of the format:
{
"discount_type": "amount" | "percentage" | "usage",
"amount_discount": string,
"percentage_discount": string,
"usage_discount": string
}
where either amount_discount
, percentage_discount
, or usage_discount
is provided.
Price discount example
{
...
"id": "price_id",
"model_type": "unit",
"unit_config": {
"unit_amount": "0.50"
},
"discount": {"discount_type": "amount", "amount_discount": "175"},
}
Removing an existing discount example
{
"customer_id": "customer_id",
"plan_id": "plan_id",
"discount": null,
"price_overrides": [ ... ]
...
}
Threshold Billing
Orb supports invoicing for a subscription when a preconfigured usage threshold is hit. To enable threshold billing, pass
in an invoicing_threshold
, which is specified in the subscription's invoicing currency, when creating a subscription.
E.g. pass in 10.00
to issue an invoice when usage amounts hit $10.00 for a subscription that invoices in USD.
Request Body
- Array [
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- ]
metadata object nullable
User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null
, and the entire metadata mapping can be cleared by setting metadata
to null
.
The plan that the given subscription should be switched to. Note that either this property or external_plan_id
must be specified.
The external_plan_id of the plan that the given subscription should be switched to. Note that either this property or plan_id
must be specified.
price_overrides object[] nullable
Optionally provide a list of overrides for prices on the plan
Possible values: [unit
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
unit_config object required
Rate per unit of usage
Possible values: [package
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
package_config object required
A currency amount to rate usage by
An integer amount to represent package size. For example, 1000 here would divide usage by 1000 before multiplying by package_amount in rating
Possible values: [matrix
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
matrix_config object required
One or two event property values to evaluate matrix groups by
Default per unit rate for any usage not bucketed into a specified matrix_value
matrix_values object[] required
Matrix values for specified matrix grouping keys
Unit price for the specified dimension_values
One or two matrix keys to filter usage to this Matrix value by. For example, ["region", "tier"] could be used to filter cloud usage by a cloud region and an instance tier.
Possible values: [tiered
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
tiered_config object required
tiers object[] required
Tiers for rating based on total usage quantities into the specified tier
Inclusive tier starting value
Exclusive tier ending value. If null, this is treated as the last tier
Amount per unit
Possible values: [tiered_bps
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
tiered_bps_config object required
tiers object[] required
Tiers for a Graduated BPS pricing model, where usage is bucketed into specified tiers
Inclusive tier starting value
Exclusive tier ending value
Per-event basis point rate
Per unit maximum to charge
Possible values: [bps
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
bps_config object required
Basis point take rate per event
Optional currency amount maximum to cap spend per event
Possible values: [bulk_bps
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
bulk_bps_config object required
tiers object[] required
Tiers for a bulk BPS pricing model where all usage is aggregated to a single tier based on total volume
Upper bound for tier
Basis points to rate on
The maximum amount to charge for any one event
Possible values: [bulk
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
bulk_config object required
tiers object[] required
Bulk tiers for rating based on total usage volume
Upper bound for this tier
Amount per unit
Possible values: [threshold_total_amount
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
threshold_total_amount_config object required
Possible values: [tiered_package
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
tiered_package_config object required
Possible values: [tiered_with_minimum
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
tiered_with_minimum_config object required
Possible values: [package_with_allocation
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
package_with_allocation_config object required
Possible values: [unit_with_percent
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
unit_with_percent_config object required
Possible values: [grouped_allocation
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
grouped_allocation_config object required
Possible values: [grouped_with_prorated_minimum
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
grouped_with_prorated_minimum_config object required
Possible values: [bulk_with_proration
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
bulk_with_proration_config object required
Possible values: [unit_with_proration
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
unit_with_proration_config object required
Possible values: [tiered_with_proration
]
The subscription's override minimum amount for the plan.
The subscription's override maximum amount for the plan.
The currency of the price. If not provided, the currency of the plan will be used.
The per unit conversion rate of the price currency to the invoicing currency.
discount object nullable
Possible values: [percentage
, trial
, usage
, amount
]
Only available if discount_type is percentage
. This is a number between 0 and 1.
Only available if discount_type is trial
Only available if discount_type is usage
. Number of usage units that this discount is for
Only available if discount_type is amount
.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
The starting quantity of the price, if the price is a fixed price.
tiered_with_proration_config object required
The net terms determines the difference between the invoice date and the issue date for the invoice. If you intend the invoice to be due on issue, set this to 0. If not provided, this defaults to the value specified in the plan.
Determines whether issued invoices for this subscription will automatically be charged with the saved payment method on the due date. If not specified, this defaults to the behavior configured for this customer.
Determines the default memo on this subscription's invoices. Note that if this is not provided, it is determined by the plan configuration.
Redemption code to be used for this subscription. If the coupon cannot be found by its redemption code, or cannot be redeemed, an error response will be returned and the subscription creation or plan change will not be scheduled.
When this subscription's accrued usage reaches this threshold, an invoice will be issued for the subscription. If not specified, invoices will only be issued at the end of the billing period.
The phase of the plan to start with
Possible values: [google
, aws
, azure
]
Default value: false
billing_cycle_anchor_configuration object nullable
Possible values: >= 1
and <= 31
The day of the month on which the billing cycle is anchored. If the maximum number of days in a month is greater than this value, the last day of the month is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing period begins on the 30th.
Possible values: >= 1
and <= 12
The month on which the billing cycle is anchored (e.g. a quarterly price anchored in February would have cycles starting February, May, August, and November).
The year on which the billing cycle is anchored (e.g. a 2 year billing cycle anchored on 2021 would have cycles starting on 2021, 2023, 2025, etc.).
- 201
- 400
- 401
- 404
- 409
- 413
- 429
- 500
Created
Response Headers
Schema
- Array [
- ]
- Array [
- ]
- Array [
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- ]
- Array [
- ]
- Array [
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
.
customer object required
A customer is a buyer of your products, and the other party to the billing relationship.
In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these
match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an
external_customer_id
with your own identifier. See
Customer ID Aliases for further information about how these
aliases work in Orb.
In addition to having an identifier in your system, a customer may exist in a payment provider solution like
Stripe. Use the payment_provider_id
and the payment_provider
enum field to express this mapping.
A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.
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
.
An optional user-defined ID for this customer resource, used throughout the system as an alias for this Customer. Use this field to identify a customer by an existing identifier in your system.
The full name of the customer
A valid customer email, to be used for notifications. When Orb triggers payment through a payment gateway, this email will be used for any automatically issued receipts.
A timezone identifier from the IANA timezone database, such as "America/Los_Angeles". This "defaults to your account's timezone if not set. This cannot be changed after customer creation.
The ID of this customer in an external payments solution, such as Stripe. This is used for creating charges or invoices in the external system via Orb.
Possible values: [quickbooks
, bill.com
, stripe_charge
, stripe_invoice
, netsuite
]
This is used for creating charges or invoices in an external system via Orb. When not in test mode, the connection must first be configured in the Orb webapp.
shipping_address object nullable
billing_address object nullable
The customer's current balance in their currency.
tax_id object nullable
Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.
Supported Tax ID Countries and Types
Country | Type | Description |
---|---|---|
Andorra | ad_nrt | Andorran NRT Number |
Argentina | ar_cuit | Argentinian Tax ID Number |
Australia | au_abn | Australian Business Number (AU ABN) |
Australia | au_arn | Australian Taxation Office Reference Number |
Austria | eu_vat | European VAT Number |
Bahrain | bh_vat | Bahraini VAT Number |
Belgium | eu_vat | European VAT Number |
Bolivia | bo_tin | Bolivian Tax ID |
Brazil | br_cnpj | Brazilian CNPJ Number |
Brazil | br_cpf | Brazilian CPF Number |
Bulgaria | bg_uic | Bulgaria Unified Identification Code |
Bulgaria | eu_vat | European VAT Number |
Canada | ca_bn | Canadian BN |
Canada | ca_gst_hst | Canadian GST/HST Number |
Canada | ca_pst_bc | Canadian PST Number (British Columbia) |
Canada | ca_pst_mb | Canadian PST Number (Manitoba) |
Canada | ca_pst_sk | Canadian PST Number (Saskatchewan) |
Canada | ca_qst | Canadian QST Number (Québec) |
Chile | cl_tin | Chilean TIN |
China | cn_tin | Chinese Tax ID |
Colombia | co_nit | Colombian NIT Number |
Costa Rica | cr_tin | Costa Rican Tax ID |
Croatia | eu_vat | European VAT Number |
Cyprus | eu_vat | European VAT Number |
Czech Republic | eu_vat | European VAT Number |
Denmark | eu_vat | European VAT Number |
Dominican Republic | do_rcn | Dominican RCN Number |
Ecuador | ec_ruc | Ecuadorian RUC Number |
Egypt | eg_tin | Egyptian Tax Identification Number |
El Salvador | sv_nit | El Salvadorian NIT Number |
Estonia | eu_vat | European VAT Number |
EU | eu_oss_vat | European One Stop Shop VAT Number for non-Union scheme |
Finland | eu_vat | European VAT Number |
France | eu_vat | European VAT Number |
Georgia | ge_vat | Georgian VAT |
Germany | eu_vat | European VAT Number |
Greece | eu_vat | European VAT Number |
Hong Kong | hk_br | Hong Kong BR Number |
Hungary | eu_vat | European VAT Number |
Hungary | hu_tin | Hungary Tax Number (adószám) |
Iceland | is_vat | Icelandic VAT |
India | in_gst | Indian GST Number |
Indonesia | id_npwp | Indonesian NPWP Number |
Ireland | eu_vat | European VAT Number |
Israel | il_vat | Israel VAT |
Italy | eu_vat | European VAT Number |
Japan | jp_cn | Japanese Corporate Number (Hōjin Bangō) |
Japan | jp_rn | Japanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō) |
Japan | jp_trn | Japanese Tax Registration Number (Tōroku Bangō) |
Kazakhstan | kz_bin | Kazakhstani Business Identification Number |
Kenya | ke_pin | Kenya Revenue Authority Personal Identification Number |
Latvia | eu_vat | European VAT Number |
Liechtenstein | li_uid | Liechtensteinian UID Number |
Lithuania | eu_vat | European VAT Number |
Luxembourg | eu_vat | European VAT Number |
Malaysia | my_frp | Malaysian FRP Number |
Malaysia | my_itn | Malaysian ITN |
Malaysia | my_sst | Malaysian SST Number |
Malta | eu_vat | European VAT Number |
Mexico | mx_rfc | Mexican RFC Number |
Netherlands | eu_vat | European VAT Number |
New Zealand | nz_gst | New Zealand GST Number |
Nigeria | ng_tin | Nigerian Tax Identification Number |
Norway | no_vat | Norwegian VAT Number |
Norway | no_voec | Norwegian VAT on e-commerce Number |
Oman | om_vat | Omani VAT Number |
Peru | pe_ruc | Peruvian RUC Number |
Philippines | ph_tin | Philippines Tax Identification Number |
Poland | eu_vat | European VAT Number |
Portugal | eu_vat | European VAT Number |
Romania | eu_vat | European VAT Number |
Romania | ro_tin | Romanian Tax ID Number |
Russia | ru_inn | Russian INN |
Russia | ru_kpp | Russian KPP |
Saudi Arabia | sa_vat | Saudi Arabia VAT |
Serbia | rs_pib | Serbian PIB Number |
Singapore | sg_gst | Singaporean GST |
Singapore | sg_uen | Singaporean UEN |
Slovakia | eu_vat | European VAT Number |
Slovenia | eu_vat | European VAT Number |
Slovenia | si_tin | Slovenia Tax Number (davčna številka) |
South Africa | za_vat | South African VAT Number |
South Korea | kr_brn | Korean BRN |
Spain | es_cif | Spanish NIF Number (previously Spanish CIF Number) |
Spain | eu_vat | European VAT Number |
Sweden | eu_vat | European VAT Number |
Switzerland | ch_vat | Switzerland VAT Number |
Taiwan | tw_vat | Taiwanese VAT |
Thailand | th_vat | Thai VAT |
Turkey | tr_tin | Turkish Tax Identification Number |
Ukraine | ua_vat | Ukrainian VAT |
United Arab Emirates | ae_trn | United Arab Emirates TRN |
United Kingdom | eu_vat | Northern Ireland VAT Number |
United Kingdom | gb_vat | United Kingdom VAT Number |
United States | us_ein | United States EIN |
Uruguay | uy_ruc | Uruguayan RUC Number |
Venezuela | ve_rif | Venezuelan RIF Number |
Vietnam | vn_tin | Vietnamese Tax ID Number |
Possible values: [AD
, AE
, AR
, AT
, AU
, BE
, BG
, BH
, BO
, BR
, CA
, CH
, CL
, CN
, CO
, CR
, CY
, CZ
, DE
, DK
, EE
, DO
, EC
, EG
, ES
, EU
, FI
, FR
, GB
, GE
, GR
, HK
, HR
, HU
, ID
, IE
, IL
, IN
, IS
, IT
, JP
, KE
, KR
, KZ
, LI
, LT
, LU
, LV
, MT
, MX
, MY
, NG
, NL
, NO
, NZ
, OM
, PE
, PH
, PL
, PT
, RO
, RS
, RU
, SA
, SE
, SG
, SI
, SK
, SV
, TH
, TR
, TW
, UA
, US
, UY
, VE
, VN
, ZA
]
Possible values: [ad_nrt
, ae_trn
, ar_cuit
, eu_vat
, au_abn
, au_arn
, bg_uic
, bh_vat
, bo_tin
, br_cnpj
, br_cpf
, ca_bn
, ca_gst_hst
, ca_pst_bc
, ca_pst_mb
, ca_pst_sk
, ca_qst
, ch_vat
, cl_tin
, cn_tin
, co_nit
, cr_tin
, do_rcn
, ec_ruc
, eg_tin
, es_cif
, eu_oss_vat
, gb_vat
, ge_vat
, hk_br
, hu_tin
, id_npwp
, il_vat
, in_gst
, is_vat
, jp_cn
, jp_rn
, jp_trn
, ke_pin
, kr_brn
, kz_bin
, li_uid
, mx_rfc
, my_frp
, my_itn
, my_sst
, ng_tin
, no_vat
, no_voec
, nz_gst
, om_vat
, pe_ruc
, ph_tin
, ro_tin
, rs_pib
, ru_inn
, ru_kpp
, sa_vat
, sg_gst
, sg_uen
, si_tin
, sv_nit
, th_vat
, tr_tin
, tw_vat
, ua_vat
, us_ein
, uy_ruc
, ve_rif
, vn_tin
, za_vat
]
accounting_sync_configuration object nullable
accounting_providers object[] required
Possible values: [quickbooks
, netsuite
]
reporting_configuration object nullable
plan object required
The Plan resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the Price resource.
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
.
Possible values: [active
, archived
, draft
]
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
product object required
trial_config object required
Possible values: [days
]
plan_phases object[] nullable required
How many terms of length duration_unit
this phase is active for. If null, this phase is evergreen and active indefinitely
Possible values: [daily
, monthly
, quarterly
, semi_annual
, annual
]
Determines the ordering of the phase in a plan's lifecycle. 1 = first phase.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
base_plan object nullable
An optional user-defined ID for this plan resource, used throughout the system as an alias for this Plan. Use this field to identify a plan by an existing identifier in your system.
The parent plan id if the given plan was created by overriding one or more of the parent's prices
An optional user-defined ID for this plan resource, used throughout the system as an alias for this Plan. Use this field to identify a plan by an existing identifier in your system.
An ISO 4217 currency string or custom pricing unit (credits
) for this plan's prices.
An ISO 4217 currency string for which this plan is billed in. Matches currency
unless currency
is a custom pricing unit.
Determines the difference between the invoice issue date and the due date. A value of "0" here signifies that invoices are due on issue, whereas a value of "30" means that the customer has a month to pay the invoice before its overdue. Note that individual subscriptions or invoices may set a different net terms configuration.
The default memo text on the invoices corresponding to subscriptions on this plan. Note that each subscription may configure its own memo.
prices object[] required
Prices for this plan. If the plan has phases, this includes prices across all phases of the plan.
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [unit
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
unit_config object required
Rate per unit of usage
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [package
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
package_config object required
A currency amount to rate usage by
An integer amount to represent package size. For example, 1000 here would divide usage by 1000 before multiplying by package_amount in rating
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [matrix
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
matrix_config object required
One or two event property values to evaluate matrix groups by
Default per unit rate for any usage not bucketed into a specified matrix_value
matrix_values object[] required
Matrix values for specified matrix grouping keys
Unit price for the specified dimension_values
One or two matrix keys to filter usage to this Matrix value by. For example, ["region", "tier"] could be used to filter cloud usage by a cloud region and an instance tier.
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [tiered
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
tiered_config object required
tiers object[] required
Tiers for rating based on total usage quantities into the specified tier
Inclusive tier starting value
Exclusive tier ending value. If null, this is treated as the last tier
Amount per unit
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [tiered_bps
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
tiered_bps_config object required
tiers object[] required
Tiers for a Graduated BPS pricing model, where usage is bucketed into specified tiers
Inclusive tier starting value
Exclusive tier ending value
Per-event basis point rate
Per unit maximum to charge
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [bps
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
bps_config object required
Basis point take rate per event
Optional currency amount maximum to cap spend per event
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [bulk_bps
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
bulk_bps_config object required
tiers object[] required
Tiers for a bulk BPS pricing model where all usage is aggregated to a single tier based on total volume
Upper bound for tier
Basis points to rate on
The maximum amount to charge for any one event
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [bulk
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
bulk_config object required
tiers object[] required
Bulk tiers for rating based on total usage volume
Upper bound for this tier
Amount per unit
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [threshold_total_amount
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
threshold_total_amount_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [tiered_package
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
tiered_package_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [grouped_tiered
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
grouped_tiered_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [tiered_with_minimum
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
tiered_with_minimum_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [tiered_package_with_minimum
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
tiered_package_with_minimum_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [package_with_allocation
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
package_with_allocation_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [unit_with_percent
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
unit_with_percent_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [matrix_with_allocation
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
matrix_with_allocation_config object required
One or two event property values to evaluate matrix groups by
Default per unit rate for any usage not bucketed into a specified matrix_value
matrix_values object[] required
Matrix values for specified matrix grouping keys
Unit price for the specified dimension_values
One or two matrix keys to filter usage to this Matrix value by. For example, ["region", "tier"] could be used to filter cloud usage by a cloud region and an instance tier.
Allocation to be used to calculate the 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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [tiered_with_proration
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
tiered_with_proration_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [unit_with_proration
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
unit_with_proration_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [grouped_allocation
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
grouped_allocation_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [grouped_with_prorated_minimum
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
grouped_with_prorated_minimum_config object required
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
.
Possible values: [usage_price
, fixed_price
]
Possible values: [bulk_with_proration
]
Possible values: [one_time
, monthly
, quarterly
, semi_annual
, annual
, custom
]
billing_cycle_configuration object required
Possible values: [day
, month
]
invoicing_cycle_configuration object nullable
Possible values: [day
, month
]
billable_metric object nullable
item object required
credit_allocation object nullable
discount object nullable
Possible values: [percentage
]
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
Possible values: <= 1
Only available if discount_type is percentage
. This is a number between 0 and 1.
Possible values: [trial
]
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 trial
Only available if discount_type is trial
Possible values: [usage
]
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 usage
. Number of usage units that this discount is for
Possible values: [amount
]
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 amount
.
minimum object nullable
Minimum amount applied
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
maximum object nullable
Maximum amount applied
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
bulk_with_proration_config object required
The date Orb starts billing for this subscription.
The date Orb stops billing for this subscription.
The start date of the current billing period. This is an inclusive timestamp; the instant returned is exactly the beginning of the billing period. Set to null if the subscription is not currently active.
The end of the current billing period. This is an exclusive timestamp, such that the instant returned is not part of the billing period. Set to null for subscriptions that are not currently active.
Possible values: [active
, ended
, upcoming
]
trial_info object required
The current plan phase that is active, only if the subscription's plan has phases.
fixed_fee_quantity_schedule object[] required
Determines the default memo on this subscriptions' invoices. Note that if this is not provided, it is determined by the plan configuration.
Determines whether issued invoices for this subscription will automatically be charged with the saved payment method on the due date. This property defaults to the plan's behavior. If null, defaults to the customer's setting.
Determines the difference between the invoice issue date for subscription invoices as the date that they are due. A value of 0
here represents that the invoice is due on issue, whereas a value of 30
represents that the customer has a month to pay the invoice.
redeemed_coupon object nullable
Possible values: >= 1
and <= 31
The day of the month on which the billing cycle is anchored. If the maximum number of days in a month is greater than this value, the last day of the month is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing period begins on the 30th.
billing_cycle_anchor_configuration object required
Possible values: >= 1
and <= 31
The day of the month on which the billing cycle is anchored. If the maximum number of days in a month is greater than this value, the last day of the month is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing period begins on the 30th.
Possible values: >= 1
and <= 12
The month on which the billing cycle is anchored (e.g. a quarterly price anchored in February would have cycles starting February, May, August, and November).
The year on which the billing cycle is anchored (e.g. a 2 year billing cycle anchored on 2021 would have cycles starting on 2021, 2023, 2025, etc.).
price_intervals object[] required
The price intervals for this subscription.
The start date of the price interval. This is the date that Orb starts billing for this price.
The end date of the price interval. This is the date that Orb stops billing for this price.
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.
Unit pricing
With unit pricing, each unit costs a fixed amount.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
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
...
}
object
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.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
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
...
}
object
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.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
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
...
}
object
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.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
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
...
}
object
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.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
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
...
}
object
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.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
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
...
}
object
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.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
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
...
}
object
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.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config": {
"default_unit_amount": "3.00",
"dimensions": [
"cluster_name",
"region"
],
"matrix_values": [
{
"dimension_values": [
"alpha",
"west"
],
"unit_amount": "2.00"
},
...
]
}
}
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
...
}
object
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.
{
...
"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.
{
...
"model_type": "tiered",
"tiered_config": {
"tiers": [
{
"first_unit": 1,
"last_unit": 10,
"unit_amount": "0.50"
},
{
"first_unit": 11,
"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 5, then 4 units will be billed as 5 and 6 units will be billed at 10.
{
...
"model_type": "package",
"package_config": {
"package_amount": "0.80",
"package_size": 10
}
...
}
BPS pricing
BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a percent (the number of basis points to charge), as well as a cap per event to assess. For example, this would allow you to assess a fee of 0.25% on every payment you process, with a maximum charge of $25 per payment.
{
...
"model_type": "bps",
"bps_config": {
"bps": 125,
"per_unit_maximum": "11.00"
}
...
}
Bulk BPS pricing
Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the total quantity across all events. Similar to bulk pricing, the BPS parameters of a given event depends on the tier range that the billing period falls into. Each tier range is defined by an upper bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.
...
"model_type": "bulk_bps",
"bulk_bps_config": {
"tiers": [
{
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
Tiered BPS pricing
Tiered BPS pricing specifies BPS parameters in a graduated manner, where an event's applicable parameter is a function of its marginal addition to the period total. Similar to tiered pricing, the BPS parameters of a given event 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 few payments may have a 0.8 BPS take-rate and all payments after a specific volume may incur a take-rate of 0.5 BPS each.
...
"model_type": "tiered_bps",
"tiered_bps_config": {
"tiers": [
{
"minimum_amount": "0",
"maximum_amount": "1000000.00",
"bps": 125,
"per_unit_maximum": "19.00"
},
{
"minimum_amount": "1000000.00",
"maximum_amount": null,
"bps": 115,
"per_unit_maximum": "4.00"
}
]
}
...
}
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
.
{
"model_type": "matrix"
"matrix_config":