Skip to main content

Add or edit price intervals​

This endpoint is used to add and edit subscription price intervals. By making modifications to a subscription’s price intervals, you can flexibly and atomically control the billing behavior of a subscription.

Adding price intervals​

Prices can be added as price intervals to a subscription by specifying them in the add array. A price_id or external_price_id from an add-on price or previously removed plan price can be specified to reuse an existing price definition (however, please note that prices from other plans cannot be added to the subscription). Additionally, a new price can be specified using the price field — this price will be created automatically.

A start_date must be specified for the price interval. This is the date when the price will start billing on the subscription, so this will notably result in an immediate charge at this time for any billed in advance fixed fees. The end_date will default to null, resulting in a price interval that will bill on a continually recurring basis. Both of these dates can be set in the past or the future and Orb will generate or modify invoices to ensure the subscription’s invoicing behavior is correct.

Additionally, a discount, minimum, or maximum can be specified on the price interval. This will only apply to this price interval, not any other price intervals on the subscription.

Adjustment intervals​

An adjustment interval represents the time period that a particular adjustment (a discount, minimum, or maximum) applies to the prices on a subscription. Adjustment intervals can be added to a subscription by specifying them in the add_adjustments array, or modified via the edit_adjustments array. When creating an adjustment interval, you'll need to provide the definition of the new adjustment (the type of adjustment, and which prices it applies to), as well as the start and end dates for the adjustment interval. The start and end dates of an existing adjustment interval can be edited via the edit_adjustments field (just like price intervals). (To "change" the amount of a discount, minimum, or maximum, then, you'll need to end the existing interval, and create a new adjustment interval with the new amount and a start date that matches the end date of the previous interval.)

Editing price intervals​

Price intervals can be adjusted by specifying edits to make in the edit array. A price_interval_id to edit must be specified — this can be retrieved from the price_intervals field on the subscription.

A new start_date or end_date can be specified to change the range of the price interval, which will modify past or future invoices to ensure correctness. If either of these dates are unspecified, they will default to the existing date on the price interval. To remove a price interval entirely from a subscription, set the end_date to be equivalent to the start_date.

Fixed fee quantity transitions​

The fixed fee quantity transitions for a fixed fee price interval can also be specified when adding or editing by passing an array for fixed_fee_quantity_transitions. A fixed fee quantity transition must have a quantity and an effective_date, which is the date after which the new quantity will be used for billing. If a fixed fee quantity transition is scheduled at a billing period boundary, the full quantity will be billed on an invoice with the other prices on the subscription. If the fixed fee quantity transition is scheduled mid-billing period, the difference between the existing quantity and quantity specified in the transition will be prorated for the rest of the billing period and billed immediately, which will generate a new invoice.

Notably, the list of fixed fee quantity transitions passed will overwrite the existing fixed fee quantity transitions on the price interval, so the entire list of transitions must be specified to add additional transitions. The existing list of transitions can be retrieved using the fixed_fee_quantity_transitions property on a subscription’s serialized price intervals.

Path Parameters
    subscription_id string required
Request Body required
    add object[]

    A list of price intervals to add to the subscription.

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

    An ISO 4217 currency string for which this price is billed in.

    allocation_price object nullable
    currency string required

    An ISO 4217 currency string or a custom pricing unit identifier in which to bill this price.

    amount string required

    An amount of the currency to allocate to the customer at the specified cadence.

    cadence string required

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

    The cadence at which to allocate the amount to the customer.

    expires_at_end_of_cadence boolean required

    Whether the allocated amount should expire at the end of the cadence or roll over to the next period.

    start_date object required

    The start date of the price interval. This is the date that the price will start billing on the subscription.

    oneOf

    string

    The start date of the price interval. This is the date that the price will start billing on the subscription.

    end_date object nullable

    The end date of the price interval. This is the date that the price will stop billing on the subscription.

    oneOf

    string

    The end date of the price interval. This is the date that the price will stop billing on the subscription.

    fixed_fee_quantity_transitions object[] nullable

    A list of fixed fee quantity transitions to initialize on the price interval.

  • Array [
    • quantity integer required

    The quantity of the fixed fee quantity transition.

    effective_date object required

    The date that the fixed fee quantity transition should take effect.

    oneOf

    string

    The date that the fixed fee quantity transition should take effect.

  • ]
    • discounts object[] nullable

    A list of discounts to initialize on the price interval.

  • Array [
    • oneOf
    discount_type string required

    Possible values: [amount]

    amount_discount number required

    Only available if discount_type is amount.

  • ]
    • minimum_amount number nullable

    The minimum amount that will be billed for this price interval for a given billing period.

    maximum_amount number nullable

    The maximum amount that will be billed for this price interval for a given billing period.

  • ]
    • edit object[]

    A list of price intervals to edit on the subscription.

  • Array [
    • price_interval_id string required

    The id of the price interval to edit.

    start_date object

    The updated start date of this price interval. If not specified, the start date will not be updated.

    oneOf

    string

    The updated start date of this price interval. If not specified, the start date will not be updated.

    end_date object nullable

    The updated end date of this price interval. If not specified, the start date will not be updated.

    oneOf

    string

    The updated end date of this price interval. If not specified, the start date will not be updated.

    fixed_fee_quantity_transitions object[] nullable

    A list of fixed fee quantity transitions to use for this price interval. Note that this list will overwrite all existing fixed fee quantity transitions on the price interval.

  • Array [
    • quantity integer required

    The quantity of the fixed fee quantity transition.

    effective_date object required

    The date that the fixed fee quantity transition should take effect.

    oneOf

    string

    The date that the fixed fee quantity transition should take effect.

  • ]
    • billing_cycle_day integer nullable

    The updated billing cycle day for this price interval. If not specified, the billing cycle day will not be updated. Note that overlapping price intervals must have the same billing cycle day.

  • ]
    • add_adjustments object[]

    A list of adjustments to add to the subscription.

  • 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 object required

    The start date of the adjustment interval. This is the date that the adjustment will start affecting prices on the subscription.

    oneOf

    string

    The start date of the adjustment interval. This is the date that the adjustment will start affecting prices on the subscription.

    end_date object nullable

    The end date of the adjustment interval. This is the date that the adjustment will stop affecting prices on the subscription.

    oneOf

    string

    The end date of the adjustment interval. This is the date that the adjustment will stop affecting prices on the subscription.

  • ]
    • edit_adjustments object[]

    A list of adjustments to edit on the subscription.

  • Array [
    • adjustment_interval_id string required

    The id of the adjustment interval to edit.

    start_date object

    The updated start date of this adjustment interval. If not specified, the start date will not be updated.

    oneOf

    string

    The updated start date of this adjustment interval. If not specified, the start date will not be updated.

    end_date object nullable

    The updated end date of this adjustment interval. If not specified, the start date will not be updated.

    oneOf

    string

    The updated end date of this adjustment interval. If not specified, the start date will not be updated.

  • ]
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...