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

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Path Parameters

subscription_id

string

required

Body

application/json

cancel_option

enum<string>

required

Determines the timing of subscription cancellation

Available options:

end_of_subscription_term,

immediate,

requested_date

cancellation_date

string | null

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_void

boolean | null

default:

true

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

200

application/json

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.

string

required

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.

customer.metadata

object

required

customer.id

string

required

customer.external_customer_id

string | null

required

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.

customer.name

string

required

The full name of the customer

customer.email

string

required

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.

customer.timezone

string

required

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.

customer.payment_provider_id

string | null

required

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.

customer.payment_provider

enum<string> | null

required

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.

Available options:

quickbooks,

bill.com,

stripe_charge,

stripe_invoice,

netsuite

customer.created_at

string

required

customer.shipping_address

object | null

required

customer.billing_address

object | null

required

customer.balance

string

required

The customer's current balance in their currency.

customer.currency

string | null

required

customer.tax_id

object | null

required

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 |

customer.auto_collection

boolean

required

customer.exempt_from_automated_tax

boolean | null

required

customer.email_delivery

boolean

required

customer.additional_emails

string[]

required

customer.portal_url

string | null

required

customer.accounting_sync_configuration

object | null

customer.reporting_configuration

object | null

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.

plan.metadata

object

required

plan.id

string

required

plan.name

string

required

plan.description

string

required

plan.maximum_amount

string | null

required

plan.minimum_amount

string | null

required

plan.created_at

string

required

plan.status

enum<string>

required

Available options:

active,

archived,

draft

plan.maximum

object | null

required

plan.minimum

object | null

required

plan.discount

object | null

required

plan.product

object

required

plan.version

integer

required

plan.trial_config

object

required

plan.plan_phases

object[] | null

required

plan.base_plan

object | null

required

plan.base_plan_id

string | null

required

The parent plan id if the given plan was created by overriding one or more of the parent's prices

plan.external_plan_id

string | null

required

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.

plan.currency

string

requireddeprecated

An ISO 4217 currency string or custom pricing unit (credits) for this plan's prices.

plan.invoicing_currency

string

required

An ISO 4217 currency string for which this plan is billed in. Matches currency unless currency is a custom pricing unit.

plan.net_terms

integer | null

required

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.

plan.default_invoice_memo

string | null

required

The default memo text on the invoices corresponding to subscriptions on this plan. Note that each subscription may configure its own memo.

plan.prices

object[]

required

Prices for this plan. If the plan has phases, this includes prices across all phases of the plan.

plan.prices.metadata

object

required

plan.prices.id

string

required

plan.prices.name

string

required

plan.prices.external_price_id

string | null

required

plan.prices.price_type

enum<string>

required

Available options:

usage_price,

fixed_price

plan.prices.model_type

enum<string>

required

Available options:

unit

plan.prices.created_at

string

required

plan.prices.cadence

enum<string>

required

Available options:

one_time,

monthly,

quarterly,

semi_annual,

annual,

custom

plan.prices.billing_cycle_configuration

object

required

plan.prices.invoicing_cycle_configuration

object | null

required

plan.prices.billable_metric

object | null

required

plan.prices.fixed_price_quantity

number | null

required

plan.prices.plan_phase_order

integer | null

required

plan.prices.currency

string

required

plan.prices.conversion_rate

number | null

required

plan.prices.item

object

required

plan.prices.credit_allocation

object | null

required

plan.prices.discount

object | null

required

plan.prices.minimum

object | null

required

plan.prices.minimum_amount

string | null

required

plan.prices.maximum

object | null

required

plan.prices.maximum_amount

string | null

required

plan.prices.unit_config

object

required

plan.prices.dimensional_price_configuration

object | null

plan.adjustments

object[]

required

Adjustments for this plan. If the plan has phases, this includes adjustments across all phases of the plan.

start_date

string

required

The date Orb starts billing for this subscription.

end_date

string | null

required

The date Orb stops billing for this subscription.

created_at

string

required

current_billing_period_start_date

string | null

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_date

string | null

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

enum<string>

required

Available options:

active,

ended,

upcoming

trial_info

object

required

active_plan_phase_order

integer | null

required

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

fixed_fee_quantity_schedule

object[]

required

default_invoice_memo

string | null

required

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

auto_collection

boolean | null

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.

net_terms

integer

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.

redeemed_coupon

object | null

required

billing_cycle_day

integer

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.

Required range: 1 < x < 31

billing_cycle_anchor_configuration

object

required

invoicing_threshold

string | null

required

price_intervals

object[]

required

The price intervals for this subscription.

price_intervals.id

string

required

price_intervals.start_date

string

required

The start date of the price interval. This is the date that Orb starts billing for this price.

price_intervals.end_date

string | null

required

The end date of the price interval. This is the date that Orb stops billing for this price.

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

For more on the types of prices, see the core concepts documentation

price_intervals.price.metadata

object

required

price_intervals.price.id

string

required

price_intervals.price.name

string

required

price_intervals.price.external_price_id

string | null

required

price_intervals.price.price_type

enum<string>

required

Available options:

usage_price,

fixed_price

price_intervals.price.model_type

enum<string>

required

Available options:

unit

price_intervals.price.created_at

string

required

price_intervals.price.cadence

enum<string>

required

Available options:

one_time,

monthly,

quarterly,

semi_annual,

annual,

custom

price_intervals.price.billing_cycle_configuration

object

required

price_intervals.price.invoicing_cycle_configuration

object | null

required

price_intervals.price.billable_metric

object | null

required

price_intervals.price.fixed_price_quantity

number | null

required

price_intervals.price.plan_phase_order

integer | null

required

price_intervals.price.currency

string

required

price_intervals.price.conversion_rate

number | null

required

price_intervals.price.item

object

required

price_intervals.price.credit_allocation

object | null

required

price_intervals.price.discount

object | null

required

price_intervals.price.minimum

object | null

required

price_intervals.price.minimum_amount

string | null

required

price_intervals.price.maximum

object | null

required

price_intervals.price.maximum_amount

string | null

required

price_intervals.price.unit_config

object

required

price_intervals.price.dimensional_price_configuration

object | null

price_intervals.billing_cycle_day

integer

required

The day of the month that Orb bills for this price

price_intervals.fixed_fee_quantity_transitions

object[] | null

required

The fixed fee quantity transitions for this price interval. This is only relevant for fixed fees.

price_intervals.current_billing_period_start_date

string | null

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 this price interval is not currently active.

price_intervals.current_billing_period_end_date

string | null

required

The end of the current billing period. This is an exclusive timestamp, such that the instant returned is exactly the end of the billing period. Set to null if this price interval is not currently active.

adjustment_intervals

object[]

required

The adjustment intervals for this subscription.

discount_intervals

object[]

required

The discount intervals for this subscription.

minimum_intervals

object[]

required

The minimum intervals for this subscription.

maximum_intervals

object[]

required

The maximum intervals for this subscription.

Was this page helpful?

Update subscription Fetch subscription costs

API Documentation

Alert

Coupon

Credit note

Customer

Credit

Dimensional Price Group

Event

Invoice

Item

Metric

Availability

Plan

Price

Subscription

Price interval

Cancel subscription

Backdated cancellations

Authorizations

Path Parameters

Body

Response

Supported Tax ID Countries and Types