v1

latestOpenAPI 3.1.02026-07-261444991.2 MB

Subscription

Cancel subscription

This endpoint can be used to cancel an existing subscription. It returns the serialized subscription object with an end_date parameter that signifies when the subscription will transition to an ended state.

The body parameter cancel_option determines the cancellation behavior. Orb supports three cancellation options:

end_of_subscription_term: stops the subscription from auto-renewing. Subscriptions that have been cancelled with this option can still incur charges for the remainder of their term:
- Issuing this cancellation request for a monthly subscription will keep the subscription active until the start of the subsequent month, and potentially issue an invoice for any usage charges incurred in the intervening period.
- Issuing this cancellation request for a quarterly subscription will keep the subscription active until the end of the quarter and potentially issue an invoice for any usage charges incurred in the intervening period.
- Issuing this cancellation request for a yearly subscription will keep the subscription active for the full year. For example, a yearly subscription starting on 2021-11-01 and cancelled on 2021-12-08 will remain active until 2022-11-01 and potentially issue charges in the intervening months for any recurring monthly usage charges in its plan.
- Note: If a subscription's plan contains prices with difference cadences, the end of term date will be determined by the largest cadence value. For example, cancelling end of term for a subscription with a quarterly fixed fee with a monthly usage fee will result in the subscription ending at the end of the quarter.
immediate: ends the subscription immediately, setting the end_date to the current time:
- Subscriptions that have been cancelled with this option will be invoiced immediately. This invoice will include any usage fees incurred in the billing period up to the cancellation, along with any prorated recurring fees for the billing period, if applicable.
- Note: If the subscription has a recurring fee that was paid in-advance, the prorated amount for the remaining time period will be added to the customer's balance upon immediate cancellation. However, if the customer is ineligible to use the customer balance, the subscription cannot be cancelled immediately.
requested_date: ends the subscription on a specified date, which requires a cancellation_date to be passed in. If no timezone is provided, the customer's timezone is used. For example, a subscription starting on January 1st with a monthly price can be set to be cancelled on the first of any month after January 1st (e.g. March 1st, April 1st, May 1st). A subscription with multiple prices with different cadences defines the "term" to be the highest cadence of the prices.

Upcoming subscriptions are only eligible for immediate cancellation, which will set the end_date equal to the start_date upon cancellation.

Backdated cancellations

Orb allows you to cancel a subscription in the past as long as there are no paid invoices between the requested_date and the current time. If the cancellation is after the latest issued invoice, Orb will generate a balance refund for the current period. If the cancellation is before the most recently issued invoice, Orb will void the intervening invoice and generate a new one based on the new dates for the subscription. See the section on cancellation behaviors.

post/subscriptions/{subscription_id}/cancel

Path parameters

subscription_idstring required

Request body

cancel_option'end_of_subscription_term' | 'immediate' | 'requested_date' required

Determines the timing of subscription cancellation

cancellation_datestring date-time nullable

The date that the cancellation should take effect. This parameter can only be passed if the cancel_option is requested_date.

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.

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