Add or edit price intervals
This endpoint is used to add and edit subscription price intervals. By making modifications to a subscription’s price intervals, you can flexibly and atomically control the billing behavior of a subscription.
Adding price intervals
Prices can be added as
price intervals to a subscription by specifying them in the add array. A price_id or external_price_id from an
add-on price or previously removed plan price can be specified to reuse an existing price definition (however, please
note that prices from other plans cannot be added to the subscription). Additionally, a new price can be specified using
the price field — this price will be created automatically.
A start_date must be specified for the price
interval. This is the date when the price will start billing on the subscription, so this will notably result in an
immediate charge at this time for any billed in advance fixed fees. The end_date will default to null, resulting in a
price interval that will bill on a continually recurring basis. Both of these dates can be set in the past or the future
and Orb will generate or modify invoices to ensure the subscription’s invoicing behavior is correct.
Additionally, a discount, minimum, or maximum can be specified on the price interval. This will only apply to this price interval, not any other price intervals on the subscription.
Adjustment intervals
An adjustment interval represents the time period that a particular adjustment (a discount, minimum, or maximum) applies
to the prices on a subscription. Adjustment intervals can be added to a subscription by specifying them in the
add_adjustments array, or modified via the edit_adjustments array. When creating an adjustment interval, you’ll need
to provide the definition of the new adjustment (the type of adjustment, and which prices it applies to), as well as
the start and end dates for the adjustment interval. The start and end dates of an existing adjustment interval can be edited
via the edit_adjustments field (just like price intervals). (To “change” the amount of a discount, minimum, or maximum,
then, you’ll need to end the existing interval, and create a new adjustment interval with the new amount and a start date
that matches the end date of the previous interval.)
Editing price intervals
Price intervals can be adjusted by
specifying edits to make in the edit array. A price_interval_id to edit must be specified — this can be retrieved
from the price_intervals field on the subscription.
A new start_date or end_date can be specified to change the
range of the price interval, which will modify past or future invoices to ensure correctness. If either of these dates
are unspecified, they will default to the existing date on the price interval. To remove a price interval entirely from
a subscription, set the end_date to be equivalent to the start_date.
Fixed fee quantity transitions
The fixed fee quantity transitions for a fixed fee price interval can also be specified when adding or editing by passing an
array for fixed_fee_quantity_transitions. A fixed fee quantity transition must have a quantity and an
effective_date, which is the date after which the new quantity will be used for billing. If a fixed fee quantity
transition is scheduled at a billing period boundary, the full quantity will be billed on an invoice with the other
prices on the subscription. If the fixed fee quantity transition is scheduled mid-billing period, the difference between
the existing quantity and quantity specified in the transition will be prorated for the rest of the billing period and
billed immediately, which will generate a new invoice.
Notably, the list of fixed fee quantity transitions passed
will overwrite the existing fixed fee quantity transitions on the price interval, so the entire list of transitions must
be specified to add additional transitions. The existing list of transitions can be retrieved using the
fixed_fee_quantity_transitions property on a subscription’s serialized price intervals.
Authorizations
API Keys can be issued in the Orb's web application.
Path Parameters
Body
A list of price intervals to add to the subscription.
A list of adjustments to add to the subscription.
A list of price intervals to edit on the subscription.
A list of adjustments to edit on the subscription.
Response
The current plan phase that is active, only if the subscription's plan has phases.
The adjustment intervals for this subscription.
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.
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.
1 < x < 31The 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.
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.
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.
Determines the default memo on this subscriptions' invoices. Note that if this is not provided, it is determined by the plan configuration.
The discount intervals for this subscription.
The date Orb stops billing for this subscription.
The maximum intervals for this subscription.
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.
The minimum intervals for this subscription.
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.
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.
The price intervals for this subscription.
The date Orb starts billing for this subscription.
active, ended, upcoming Was this page helpful?