Skip to main content

Schedule plan change​

This endpoint can be used to change an existing subscription's plan. It returns the serialized updated subscription object.

The body parameter change_option determines when the plan change occurrs. Orb supports three options:

  • end_of_subscription_term: changes the plan at the end of the existing plan's term.
    • Issuing this plan change request for a monthly subscription will keep the existing plan active until the start of the subsequent month. Issuing this plan change request for a yearly subscription will keep the existing plan active for the full year. Charges incurred in the remaining period will be invoiced as normal.
    • Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, so the plan will be changed on February 1st, and invoice will be issued on February 1st for the last month of the original plan.
  • immediate: changes the plan immediately.
    • Subscriptions that have their plan changed with this option will move to the new plan immediately, and be invoiced immediately.
    • This invoice will include any usage fees incurred in the billing period up to the change, along with any prorated recurring fees for the billing period, if applicable.
    • Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, so the plan will be changed on January 15th, and an invoice will be issued for the partial month, from January 1 to January 15, on the original plan.
  • requested_date: changes the plan on the requested date (change_date).
    • If no timezone is provided, the customer's timezone is used. The change_date body parameter is required if this option is chosen.
    • Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, with a requested change_date of February 15th, so the plan will be changed on February 15th, and invoices will be issued on February 1st and February 15th.

Note that one of plan_id or external_plan_id is required in the request body for this operation.

Customize your customer's subscriptions​

Prices and adjustments in a plan can be added, removed, or replaced on the subscription when you schedule the plan change. This is useful when a customer has prices that differ from the default prices for a specific plan.

info

This feature is only available for accounts that have migrated to Subscription Overrides Version 2. You can find your Subscription Overrides Version at the bottom of your Plans page

Adding Prices​

To add prices, provide a list of objects with the key add_prices. An object in the list must specify an existing add-on price with a price_id or external_price_id field, or create a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object.

If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the price should be added to.

An object in the list can specify an optional start_date and optional end_date. This is equivalent to creating a price interval with the add/edit price intervals endpoint. If unspecified, the start or end date of the phase or subscription will be used.

An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price.

Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference this price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Removing Prices​

To remove prices, provide a list of objects with the key remove_prices. An object in the list must specify a plan price with either a price_id or external_price_id field.

Replacing Prices​

To replace prices, provide a list of objects with the key replace_prices. An object in the list must specify a plan price to replace with the replaces_price_id key, and it must specify a price to replace it with by either referencing an existing add-on price with a price_id or external_price_id field, or by creating a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object.

For fixed fees, an object in the list can supply a fixed_price_quantity instead of a price, price_id, or external_price_id field. This will update only the quantity for the price, similar to the Update price quantity endpoint.

The replacement price will have the same phase, if applicable, and the same start and end dates as the price it replaces.

An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price.

Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference the replacement price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Adding adjustments​

To add adjustments, provide a list of objects with the key add_adjustments. An object in the list must include an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint.

If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the adjustment should be added to.

An object in the list can specify an optional start_date and optional end_date. If unspecified, the start or end date of the phase or subscription will be used.

Removing adjustments​

To remove adjustments, provide a list of objects with the key remove_adjustments. An object in the list must include a key, adjustment_id, with the ID of the adjustment to be removed.

Replacing adjustments​

To replace adjustments, provide a list of objects with the key replace_adjustments. An object in the list must specify a plan adjustment to replace with the replaces_adjustment_id key, and it must specify an adjustment to replace it with by including an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint.

The replacement adjustment will have the same phase, if applicable, and the same start and end dates as the adjustment it replaces.

Price overrides (DEPRECATED)​

info

Price overrides are being phased out in favor adding/removing/replacing prices. (See Customize your customer's subscriptions)

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 a rate that is unique to the customer.

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 configuration. (See the Price resource for the specification of different price model configurations.) The numerical values can be updated, but the billable metric, cadence, type, and name of a price can not be overridden.

Maximums, and minimums​

Price overrides are used to update some or all prices in the target plan. 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 the plan. The request format for maximums and minimums is the same as those in subscription creation.

Scheduling multiple plan changes​

When scheduling multiple plan changes with the same date, the latest plan change on that day takes effect.

Prorations for in-advance fees​

By default, Orb calculates the prorated difference in any fixed fees when making a plan change, adjusting the customer balance as needed. For details on this behavior, see Modifying subscriptions.

Path Parameters
    subscription_id string required
Request Body required
    plan_id string nullable

    The plan that the given subscription should be switched to. Note that either this property or external_plan_id must be specified.

    external_plan_id string nullable

    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 undefined[] nullable deprecated

    Optionally provide a list of overrides for prices on the plan

    per_credit_overage_amount number nullable deprecated
    credits_overage_rate number nullable deprecated
    trial_duration_days integer nullable

    Possible values: < 1000000

    The duration of the trial period in days. If not provided, this defaults to the value specified in the plan. If 0 is provided, the trial on the plan will be skipped.

    net_terms integer nullable

    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.

    auto_collection boolean nullable

    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.

    default_invoice_memo string nullable

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

    coupon_redemption_code string nullable

    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.

    invoicing_threshold string nullable

    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.

    initial_phase_order integer nullable

    The phase of the plan to start with

    add_prices object[] nullable

    Additional prices to be added to the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

  • Array [
    • price_id string nullable

    The id of the price to add to the subscription.

    external_price_id string nullable

    The external price id of the price to add to the subscription.

    price object nullable
    oneOf
    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.

    property name* string nullable
    external_price_id string nullable

    An alias for the price.

    name string required

    The name of the price.

    billable_metric_id string nullable

    The id of the billable metric for the price. Only needed if the price is usage-based.

    item_id string required

    The id of the item the plan will be associated with.

    billed_in_advance boolean nullable

    If the Price represents a fixed cost, the price will be billed in-advance if this is true, and in-arrears if this is false.

    fixed_price_quantity number nullable

    If the Price represents a fixed cost, this represents the quantity of units applied.

    invoice_grouping_key string nullable

    The property used to group this price on an invoice

    cadence string required

    Possible values: [annual, semi_annual, monthly, quarterly, one_time, custom]

    The cadence to bill for this price on.

    billing_cycle_configuration object nullable

    For custom cadence: specifies the duration of the billing period in days or months.

    duration integer required

    The duration of the billing period.

    duration_unit string required

    Possible values: [day, month]

    The unit of billing period duration.

    invoicing_cycle_configuration object nullable

    Within each billing cycle, specifies the cadence at which invoices are produced. If unspecified, a single invoice is produced per billing cycle.

    duration integer required

    The duration of the billing period.

    duration_unit string required

    Possible values: [day, month]

    The unit of billing period duration.

    conversion_rate number nullable

    The per unit conversion rate of the price currency to the invoicing currency.

    model_type string required

    Possible values: [unit]

    unit_config object required
    unit_amount string required

    Rate per unit of usage

    currency string nullable

    An ISO 4217 currency string, or custom pricing unit identifier, in which this price is billed.

    reference_id string nullable

    A transient ID that can be used to reference this price when adding adjustments in the same API call.

    start_date date-time nullable

    The start date of the price interval. This is the date that the price will start billing on the subscription. If null, billing will start when the phase or subscription starts.

    end_date date-time nullable

    The end date of the price interval. This is the date that the price will stop billing on the subscription. If null, billing will end when the phase or subscription ends.

    plan_phase_order integer nullable

    The phase to add this price to.

    minimum_amount string nullable

    The subscription's minimum amount for this price.

    maximum_amount string nullable

    The subscription's maximum amount for this price.

    discounts object[] nullable

    The subscription's discounts for this price.

  • Array [
    • discount_type string required

    Possible values: [percentage, usage, amount]

    percentage_discount number nullable

    Only available if discount_type is percentage. This is a number between 0 and 1.

    usage_discount number nullable

    Only available if discount_type is usage. Number of usage units that this discount is for

    amount_discount string nullable

    Only available if discount_type is amount.

  • ]
  • ]
    • remove_prices object[] nullable

    Plan prices to be removed from the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

  • Array [
    • price_id string nullable

    The id of the price to remove on the subscription.

    external_price_id string nullable

    The external price id of the price to remove on the subscription.

  • ]
    • replace_prices object[] nullable

    Plan prices to be replaced with additional prices on the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

  • Array [
    • price_id string nullable

    The id of the price to add to the subscription.

    external_price_id string nullable

    The external price id of the price to add to the subscription.

    price object nullable
    oneOf
    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.

    property name* string nullable
    external_price_id string nullable

    An alias for the price.

    name string required

    The name of the price.

    billable_metric_id string nullable

    The id of the billable metric for the price. Only needed if the price is usage-based.

    item_id string required

    The id of the item the plan will be associated with.

    billed_in_advance boolean nullable

    If the Price represents a fixed cost, the price will be billed in-advance if this is true, and in-arrears if this is false.

    fixed_price_quantity number nullable

    If the Price represents a fixed cost, this represents the quantity of units applied.

    invoice_grouping_key string nullable

    The property used to group this price on an invoice

    cadence string required

    Possible values: [annual, semi_annual, monthly, quarterly, one_time, custom]

    The cadence to bill for this price on.

    billing_cycle_configuration object nullable

    For custom cadence: specifies the duration of the billing period in days or months.

    duration integer required

    The duration of the billing period.

    duration_unit string required

    Possible values: [day, month]

    The unit of billing period duration.

    invoicing_cycle_configuration object nullable

    Within each billing cycle, specifies the cadence at which invoices are produced. If unspecified, a single invoice is produced per billing cycle.

    duration integer required

    The duration of the billing period.

    duration_unit string required

    Possible values: [day, month]

    The unit of billing period duration.

    conversion_rate number nullable

    The per unit conversion rate of the price currency to the invoicing currency.

    model_type string required

    Possible values: [unit]

    unit_config object required
    unit_amount string required

    Rate per unit of usage

    currency string nullable

    An ISO 4217 currency string, or custom pricing unit identifier, in which this price is billed.

    reference_id string nullable

    A transient ID that can be used to reference this price when adding adjustments in the same API call.

    fixed_price_quantity number nullable

    The new quantity of the price, if the price is a fixed price.

    replaces_price_id string required

    The id of the price on the plan to replace in the subscription.

    minimum_amount string nullable

    The subscription's minimum amount for the replacement price.

    maximum_amount string nullable

    The subscription's maximum amount for the replacement price.

    discounts object[] nullable

    The subscription's discounts for the replacement price.

  • Array [
    • discount_type string required

    Possible values: [percentage, usage, amount]

    percentage_discount number nullable

    Only available if discount_type is percentage. This is a number between 0 and 1.

    usage_discount number nullable

    Only available if discount_type is usage. Number of usage units that this discount is for

    amount_discount string nullable

    Only available if discount_type is amount.

  • ]
  • ]
    • add_adjustments object[] nullable

    Additional adjustments to be added to the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

  • Array [
    • adjustment object
    oneOf
    applies_to_price_ids string[] required

    The set of price IDs to which this adjustment applies.

    adjustment_type string required

    Possible values: [percentage_discount]

    percentage_discount number required
    start_date date-time nullable

    The start date of the adjustment interval. This is the date that the adjustment will start affecting prices on the subscription. If null, the adjustment will start when the phase or subscription starts.

    end_date date-time nullable

    The end date of the adjustment interval. This is the date that the adjustment will stop affecting prices on the subscription. If null, the adjustment will start when the phase or subscription starts.

    plan_phase_order integer nullable

    The phase to add this adjustment to.

  • ]
    • remove_adjustments object[] nullable

    Plan adjustments to be removed from the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

  • Array [
    • adjustment_id string required

    The id of the adjustment to remove on the subscription.

  • ]
    • replace_adjustments object[] nullable

    Plan adjustments to be replaced with additional adjustments on the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

  • Array [
    • adjustment object
    oneOf
    applies_to_price_ids string[] required

    The set of price IDs to which this adjustment applies.

    adjustment_type string required

    Possible values: [percentage_discount]

    percentage_discount number required
    replaces_adjustment_id string required

    The id of the adjustment on the plan to replace in the subscription.

  • ]
    • change_option string required

    Possible values: [requested_date, end_of_subscription_term, immediate]

    change_date date-time nullable

    The date that the plan change should take effect. This parameter can only be passed if the change_option is requested_date.

    align_billing_with_plan_change_date boolean nullable

    [DEPRECATED] Use billing_cycle_alignment instead. Reset billing periods to be aligned with the plan change's effective date.

    billing_cycle_alignment string nullable

    Possible values: [unchanged, plan_change_date, start_of_month]

    Default value: unchanged

    Reset billing periods to be aligned with the plan change's effective date or start of the month. Defaults to unchanged which keeps subscription's existing billing cycle alignment.

    plan_version_number integer nullable

    Specifies which version of the plan to change to. If null, the default version will be used.

Responses

OK

Response Headers
    Schema
      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.

      property name* string
      id 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.

      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.

      property name* string
      id string required
      external_customer_id string nullable 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.

      name string required

      The full name of the 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.

      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.

      payment_provider_id string nullable 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.

      payment_provider string nullable required

      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.

      created_at date-time required
      shipping_address object nullable
      line1 string nullable required
      line2 string nullable required
      city string nullable required
      state string nullable required
      postal_code string nullable required
      country string nullable required
      billing_address object nullable
      line1 string nullable required
      line2 string nullable required
      city string nullable required
      state string nullable required
      postal_code string nullable required
      country string nullable required
      balance string required

      The customer's current balance in their currency.

      currency string nullable required
      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​

      CountryTypeDescription
      Andorraad_nrtAndorran NRT Number
      Argentinaar_cuitArgentinian Tax ID Number
      Australiaau_abnAustralian Business Number (AU ABN)
      Australiaau_arnAustralian Taxation Office Reference Number
      Austriaeu_vatEuropean VAT Number
      Bahrainbh_vatBahraini VAT Number
      Belgiumeu_vatEuropean VAT Number
      Boliviabo_tinBolivian Tax ID
      Brazilbr_cnpjBrazilian CNPJ Number
      Brazilbr_cpfBrazilian CPF Number
      Bulgariabg_uicBulgaria Unified Identification Code
      Bulgariaeu_vatEuropean VAT Number
      Canadaca_bnCanadian BN
      Canadaca_gst_hstCanadian GST/HST Number
      Canadaca_pst_bcCanadian PST Number (British Columbia)
      Canadaca_pst_mbCanadian PST Number (Manitoba)
      Canadaca_pst_skCanadian PST Number (Saskatchewan)
      Canadaca_qstCanadian QST Number (Québec)
      Chilecl_tinChilean TIN
      Chinacn_tinChinese Tax ID
      Colombiaco_nitColombian NIT Number
      Costa Ricacr_tinCosta Rican Tax ID
      Croatiaeu_vatEuropean VAT Number
      Cypruseu_vatEuropean VAT Number
      Czech Republiceu_vatEuropean VAT Number
      Denmarkeu_vatEuropean VAT Number
      Dominican Republicdo_rcnDominican RCN Number
      Ecuadorec_rucEcuadorian RUC Number
      Egypteg_tinEgyptian Tax Identification Number
      El Salvadorsv_nitEl Salvadorian NIT Number
      Estoniaeu_vatEuropean VAT Number
      EUeu_oss_vatEuropean One Stop Shop VAT Number for non-Union scheme
      Finlandeu_vatEuropean VAT Number
      Franceeu_vatEuropean VAT Number
      Georgiage_vatGeorgian VAT
      Germanyeu_vatEuropean VAT Number
      Greeceeu_vatEuropean VAT Number
      Hong Konghk_brHong Kong BR Number
      Hungaryeu_vatEuropean VAT Number
      Hungaryhu_tinHungary Tax Number (adószám)
      Icelandis_vatIcelandic VAT
      Indiain_gstIndian GST Number
      Indonesiaid_npwpIndonesian NPWP Number
      Irelandeu_vatEuropean VAT Number
      Israelil_vatIsrael VAT
      Italyeu_vatEuropean VAT Number
      Japanjp_cnJapanese Corporate Number (Hōjin Bangō)
      Japanjp_rnJapanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)
      Japanjp_trnJapanese Tax Registration Number (Tōroku Bangō)
      Kazakhstankz_binKazakhstani Business Identification Number
      Kenyake_pinKenya Revenue Authority Personal Identification Number
      Latviaeu_vatEuropean VAT Number
      Liechtensteinli_uidLiechtensteinian UID Number
      Lithuaniaeu_vatEuropean VAT Number
      Luxembourgeu_vatEuropean VAT Number
      Malaysiamy_frpMalaysian FRP Number
      Malaysiamy_itnMalaysian ITN
      Malaysiamy_sstMalaysian SST Number
      Maltaeu_vat European VAT Number
      Mexicomx_rfcMexican RFC Number
      Netherlandseu_vatEuropean VAT Number
      New Zealandnz_gstNew Zealand GST Number
      Nigeriang_tinNigerian Tax Identification Number
      Norwayno_vatNorwegian VAT Number
      Norwayno_voecNorwegian VAT on e-commerce Number
      Omanom_vatOmani VAT Number
      Perupe_rucPeruvian RUC Number
      Philippinesph_tin Philippines Tax Identification Number
      Polandeu_vatEuropean VAT Number
      Portugaleu_vatEuropean VAT Number
      Romaniaeu_vatEuropean VAT Number
      Romaniaro_tinRomanian Tax ID Number
      Russiaru_innRussian INN
      Russiaru_kppRussian KPP
      Saudi Arabiasa_vatSaudi Arabia VAT
      Serbiars_pibSerbian PIB Number
      Singaporesg_gstSingaporean GST
      Singaporesg_uenSingaporean UEN
      Slovakiaeu_vatEuropean VAT Number
      Sloveniaeu_vatEuropean VAT Number
      Sloveniasi_tinSlovenia Tax Number (davčna številka)
      South Africaza_vatSouth African VAT Number
      South Koreakr_brnKorean BRN
      Spaines_cifSpanish NIF Number (previously Spanish CIF Number)
      Spaineu_vatEuropean VAT Number
      Swedeneu_vatEuropean VAT Number
      Switzerlandch_vatSwitzerland VAT Number
      Taiwantw_vatTaiwanese VAT
      Thailandth_vatThai VAT
      Turkeytr_tinTurkish Tax Identification Number
      Ukraineua_vatUkrainian VAT
      United Arab Emiratesae_trnUnited Arab Emirates TRN
      United Kingdomeu_vatNorthern Ireland VAT Number
      United Kingdomgb_vatUnited Kingdom VAT Number
      United Statesus_einUnited States EIN
      Uruguayuy_rucUruguayan RUC Number
      Venezuelave_rifVenezuelan RIF Number
      Vietnamvn_tinVietnamese Tax ID Number
      country string required

      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]

      type string required

      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]

      value string required
      auto_collection boolean required
      exempt_from_automated_tax boolean nullable required
      email_delivery boolean required
      additional_emails string[] required
      portal_url string nullable required
      accounting_sync_configuration object nullable
      excluded boolean required
      accounting_providers object[] required
    • Array [
      • provider_type string required

      Possible values: [quickbooks, netsuite]

      external_provider_id string nullable required
    • ]
      • reporting_configuration object nullable
      exempt boolean required
      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.

      property name* string
      id string required
      name string required
      description string required
      maximum_amount string nullable required
      minimum_amount string nullable required
      created_at date-time required
      status string required

      Possible values: [active, archived, draft]

      maximum object nullable
      maximum_amount string required

      Maximum amount applied

      applies_to_price_ids string[] required

      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 string required

      Minimum amount applied

      applies_to_price_ids string[] required

      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
      oneOf
      discount_type string required

      Possible values: [percentage]

      applies_to_price_ids string[] required

      List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

      reason string nullable
      percentage_discount number required

      Possible values: <= 1

      Only available if discount_type is percentage. This is a number between 0 and 1.

      product object required
      created_at date-time required
      id string required
      name string required
      version integer required
      trial_config object required
      trial_period integer nullable required
      trial_period_unit string required

      Possible values: [days]

      plan_phases object[] nullable required
    • Array [
      • id string required
      description string nullable required
      duration integer nullable required

      How many terms of length duration_unit this phase is active for. If null, this phase is evergreen and active indefinitely

      duration_unit string nullable required

      Possible values: [daily, monthly, quarterly, semi_annual, annual]

      name string required
      order integer required

      Determines the ordering of the phase in a plan's lifecycle. 1 = first phase.

      minimum object nullable
      minimum_amount string required

      Minimum amount applied

      applies_to_price_ids string[] required

      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 string required

      Maximum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

      maximum_amount string nullable required
      minimum_amount string nullable required
      discount object nullable
      oneOf
      discount_type string required

      Possible values: [percentage]

      applies_to_price_ids string[] required

      List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

      reason string nullable
      percentage_discount number required

      Possible values: <= 1

      Only available if discount_type is percentage. This is a number between 0 and 1.

    • ]
      • base_plan object nullable
      id string nullable required
      external_plan_id string nullable 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.

      name string nullable required
      base_plan_id string nullable required

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

      external_plan_id string nullable 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.

      currency string deprecated

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

      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.

      net_terms integer nullable 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.

      default_invoice_memo string nullable required

      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.

    • Array [
      • oneOf
      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.

      property name* string
      id string required
      name string required
      external_price_id string nullable required
      price_type string required

      Possible values: [usage_price, fixed_price]

      model_type string required

      Possible values: [unit]

      created_at date-time required
      cadence string required

      Possible values: [one_time, monthly, quarterly, semi_annual, annual, custom]

      billing_cycle_configuration object required
      duration integer required
      duration_unit string required

      Possible values: [day, month]

      invoicing_cycle_configuration object nullable
      duration integer required
      duration_unit string required

      Possible values: [day, month]

      billable_metric object nullable
      id string required
      fixed_price_quantity number nullable required
      plan_phase_order integer nullable required
      currency string required
      conversion_rate number nullable required
      item object required
      id string required
      name string required
      credit_allocation object nullable
      currency string required
      allows_rollover boolean required
      discount object nullable
      oneOf
      discount_type string required

      Possible values: [percentage]

      applies_to_price_ids string[] required

      List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

      reason string nullable
      percentage_discount number required

      Possible values: <= 1

      Only available if discount_type is percentage. This is a number between 0 and 1.

      minimum object nullable
      minimum_amount string required

      Minimum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

      minimum_amount string nullable required
      maximum object nullable
      maximum_amount string required

      Maximum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

      maximum_amount string nullable required
      unit_config object required
      unit_amount string required

      Rate per unit of usage

    • ]
      • start_date date-time required

      The date Orb starts billing for this subscription.

      end_date date-time nullable required

      The date Orb stops billing for this subscription.

      created_at date-time required
      current_billing_period_start_date 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_date 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 string required

      Possible values: [active, ended, upcoming]

      trial_info object required
      end_date date-time nullable required
      active_plan_phase_order integer nullable required

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

      fixed_fee_quantity_schedule object[] required
    • Array [
      • price_id string required
      start_date date-time required
      end_date date-time nullable required
      quantity number required
    • ]
      • default_invoice_memo string 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_collection boolean 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.

      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 nullable
      coupon_id string required
      start_date date-time required
      end_date date-time nullable required
      billing_cycle_day integer 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.

      billing_cycle_anchor_configuration object required
      day integer 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.

      month integer nullable

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

      year integer nullable

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

      invoicing_threshold string nullable required
      price_intervals object[] required

      The price intervals for this subscription.

    • Array [
      • id string required
      start_date date-time required

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

      end_date date-time nullable required

      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
          ...
      }
      oneOf

      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
          ...
      }
      billing_cycle_day integer required

      The day of the month that Orb bills for this price

      fixed_fee_quantity_transitions object[] nullable required

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

    • Array [
      • price_id string required
      effective_date date-time required
      quantity integer required
    • ]
      • current_billing_period_start_date 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 this price interval is not currently active.

      current_billing_period_end_date date-time nullable 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.

    • Array [
      • id string required
      adjustment object required
      oneOf

      object

      start_date date-time required

      The start date of the adjustment interval.

      end_date date-time nullable required

      The end date of the adjustment interval.

      applies_to_price_interval_ids string[] required

      The price interval IDs that this adjustment applies to.

    • ]
      • discount_intervals object[] required

      The discount intervals for this subscription.

    • Array [
      • oneOf
      discount_type string required

      Possible values: [amount]

      amount_discount string required

      Only available if discount_type is amount.

      start_date date-time required

      The start date of the discount interval.

      end_date date-time nullable required

      The end date of the discount interval.

      applies_to_price_ids string[] required

      The price ids that this discount interval applies to.

      applies_to_price_interval_ids string[] required

      The price interval ids that this discount interval applies to.

    • ]
      • minimum_intervals object[] required

      The minimum intervals for this subscription.

    • Array [
      • start_date date-time required

      The start date of the minimum interval.

      end_date date-time nullable required

      The end date of the minimum interval.

      applies_to_price_ids string[] required

      The price ids that this minimum interval applies to.

      applies_to_price_interval_ids string[] required

      The price interval ids that this minimum interval applies to.

      minimum_amount string required

      The minimum amount to charge in a given billing period for the price intervals this minimum applies to.

    • ]
      • maximum_intervals object[] required

      The maximum intervals for this subscription.

    • Array [
      • start_date date-time required

      The start date of the maximum interval.

      end_date date-time nullable required

      The end date of the maximum interval.

      applies_to_price_ids string[] required

      The price ids that this maximum interval applies to.

      applies_to_price_interval_ids string[] required

      The price interval ids that this maximum interval applies to.

      maximum_amount string required

      The maximum amount to charge in a given billing period for the price intervals this transform applies to.

    • ]
    Loading...