v1

latestOpenAPI 3.1.02026-07-261444991.2 MB

Subscription

Update price quantity

This endpoint can be used to update the quantity for a fixed fee.

To be eligible, the subscription must currently be active and the price specified must be a fixed fee (not usage-based). This operation will immediately update the quantity for the fee, or if a effective_date is passed in, will update the quantity on the requested date at midnight in the customer's timezone.

In order to change the fixed fee quantity as of the next draft invoice for this subscription, pass change_option=upcoming_invoice without an effective_date specified.

If the fee is an in-advance fixed fee, it will also issue an immediate invoice for the difference for the remainder of the billing period.

post/subscriptions/{subscription_id}/update_fixed_fee_quantity

Path parameters

subscription_idstring required

Request body

price_idstring required

Price for which the quantity should be updated. Must be a fixed fee.

quantitynumber required

effective_datestring date nullable

The date that the quantity change should take effect, localized to the customer's timezone. If this parameter is not passed in, the quantity change is effective according to change_option.

change_option'immediate' | 'upcoming_invoice' | 'effective_date'

Determines when the change takes effect. Note that if effective_date is specified, this defaults to effective_date. Otherwise, this defaults to immediate unless it's explicitly set to upcoming_invoice.

allow_invoice_credit_or_voidboolean nullable

If false, this request will fail if it would void an issued invoice or create a credit note. Consider using this as a safety mechanism if you do not expect existing invoices to be changed.

Example request

{
  "effective_date": "2022-12-21"
}

Response

metadataobject 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.

idstring required

namestring required

The name of the subscription.

start_datestring date-time required

The date Orb starts billing for this subscription.

end_datestring date-time nullable required

The date Orb stops billing for this subscription.

created_atstring date-time required

current_billing_period_start_datestring date-time nullable required

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.

current_billing_period_end_datestring date-time nullable required

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.

status'active' | 'ended' | 'upcoming' required

active_plan_phase_orderinteger nullable required

The current plan phase that is active, only if the subscription's plan has phases.

default_invoice_memostring nullable required

Determines the default memo on this subscriptions' invoices. Note that if this is not provided, it is determined by the plan configuration.

auto_collectionboolean nullable required

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.

auto_issuanceboolean nullable required

Determines whether invoices for this subscription will be automatically issued. This resolves the effective setting for the subscription: a subscription-level override if set, otherwise the customer-level setting, otherwise the account-level default.

net_termsinteger required

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.

billing_cycle_dayinteger required

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.

invoicing_thresholdstring nullable required