Skip to main content

Create subscription​

A subscription represents the purchase of a plan by a customer. The customer is identified by either the customer_id or the external_customer_id, and exactly one of these fields must be provided.

By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition.

The default configuration for subscriptions in Orb is In-advance billing and Beginning of month alignment (see Subscription for more details).

In order to change the alignment behavior, Orb also supports billing subscriptions on the day of the month they are created. If align_billing_with_subscription_start_date = true is specified, subscriptions have billing cycles that are aligned with their start_date. For example, a subscription that begins on January 15th will have a billing cycle from January 15th to February 15th. Every subsequent billing cycle will continue to start and invoice on the 15th.

If the "day" value is greater than the number of days in the month, the next billing cycle will start at the end of the month. For example, if the start_date is January 31st, the next billing cycle will start on February 28th.

If a customer was created with a currency, Orb only allows subscribing the customer to a plan with a matching invoicing_currency. If the customer does not have a currency set, on subscription creation, we set the customer's currency to be the invoicing_currency of the plan.

Price overrides​

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 one or more different prices for a specific plan than the plan's default prices. Any type of price can be overridden, if the correct data is provided. The billable metric, cadence, type, and name of a price can not be overridden.

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 config value in the format below. The specific numerical values can be updated, but the config value and model_type must match the existing price that is being overridden

Request format for price overrides​

Orb supports a few different pricing models out of the box. 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.

{
  ...
  "id": "price_id",
  "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. Tiered prices can be overridden with a new number of tiers or new values for first_unit, last_unit, or unit_amount.

{
  ...
  "id": "price_id",
  "model_type": "tiered",
  "tiered_config": {
    "tiers": [
      {
        "first_unit":"1",
        "last_unit": "11",
        "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). Bulk prices can be overridden with a new number of tiers or new values for maximum_units, or unit_amount.

{
  ...
  "id": "price_id",
  "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.

{
  ...
  "id": "price_id",
  "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.

{
  ...
  "id": "price_id"
  "model_type": "bps",
  "bps_config": {
    "bps": 125,
    "per_event_cap": "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 and lower bound. For example, after $1.5M of payment volume is reached, each individual payment may have a lower cap or a smaller take-rate.

{
  ...
  "id": "price_id"
  "model_type": "bulk_bps",
  "bulk_bps_config": {
    "tiers": [
      {
        "minimum_amount": "0.00",
        "maximum_amount": "1000000.00",
        "bps": 125,
        "per_event_cap": "19.00"
      },
      {
        "minimum_amount":"1000000.00",
        "maximum_amount": null,
        "bps": 115,
        "per_event_cap": "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.

{
  ...
  "id": "price_id"
  "model_type": "tiered_bps",
  "tiered_bps_config": {
    "tiers": [
      {
        "minimum_amount": "0.00",
        "maximum_amount": "1000000.00",
        "bps": 125,
        "per_event_cap": "19.00"
      },
      {
        "minimum_amount":"1000000",
        "maximum_amount": null,
        "bps": 115,
        "per_event_cap": "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 follow unit pricing, and also have an additional parameter fixed_price_quantity that indicates how many of a fixed fee that should be applied for a subscription. This parameter defaults to 1.

{
  ...
  "id": "price_id",
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "2.00"
  },
  "fixed_price_quantity": 3.0
  ...
}

Maximums and Minimums​

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 a given price. If one exists for a price and null is provided for the minimum/maximum override on creation, then there will be no minimum/maximum on the new subscription. If no value is provided, then the default price maximum or minimum is used.

To add a minimum for a specific price, add minimum_amount to the specific price in the price_overrides object.

To add a maximum for a specific price, add maximum_amount to the specific price in the price_overrides object.

Minimum override example​

Price minimum override example:

{
  ...
  "id": "price_id",
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "0.50"
  },
  "minimum_amount": "100.00"
  ...
}

Removing an existing minimum example

{
  ...
  "id": "price_id",
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "0.50"
  },
  "minimum_amount": null
  ...
}

Discounts​

Discounts, like price overrides, can be useful when a new customer has negotiated a new or different discount than the default for a price. A single price price can have at most one discount. If a discount exists for a price and a null discount is provided on creation, then there will be no discount on the new subscription.

To add a discount for a specific price, add discount to the price in the price_overrides object. Discount should be a dictionary of the format:

{
  "discount_type": "amount" | "percentage" | "usage",
  "amount_discount": string,
  "percentage_discount": string,
  "usage_discount": string
}

where either amount_discount, percentage_discount, or usage_discount is provided.

Price discount example

{
  ...
  "id": "price_id",
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "0.50"
  },
  "discount": {"discount_type": "amount", "amount_discount": "175"},
}

Removing an existing discount example

{
  "customer_id": "customer_id",
  "plan_id": "plan_id",
  "discount": null,
  "price_overrides": [ ... ]
  ...
}

Threshold Billing​

Orb supports invoicing for a subscription when a preconfigured usage threshold is hit. To enable threshold billing, pass in an invoicing_threshold, which is specified in the subscription's invoicing currency, when creating a subscription. E.g. pass in 10.00 to issue an invoice when usage amounts hit $10.00 for a subscription that invoices in USD.

Request Body
    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
    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 object[] nullable

    Optionally provide a list of overrides for prices on the plan

  • Array [
    • oneOf
    id string required
    model_type string required

    Possible values: [unit]

    minimum_amount string nullable

    The subscription's override minimum amount for the plan.

    maximum_amount string nullable

    The subscription's override maximum amount for the plan.

    currency string nullable

    The currency of the price. If not provided, the currency of the plan will be used.

    conversion_rate number nullable

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

    discount object nullable
    discount_type string required

    Possible values: [percentage, trial, usage, amount]

    percentage_discount number nullable

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

    trial_amount_discount string nullable

    Only available if discount_type is trial

    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.

    applies_to_price_ids string[] nullable

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

    fixed_price_quantity number nullable

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

    unit_config object required
    unit_amount string required

    Rate per unit of usage

  • ]
    • per_credit_overage_amount number nullable deprecated
    credits_overage_rate number nullable deprecated
    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

    customer_id string nullable
    external_customer_id string nullable
    start_date date-time nullable
    end_date date-time nullable
    external_marketplace string nullable deprecated

    Possible values: [google, aws, azure]

    external_marketplace_reporting_id string nullable deprecated
    aws_region string nullable deprecated
    align_billing_with_subscription_start_date boolean

    Default value: false

    billing_cycle_anchor_configuration object nullable
    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.).

Responses

Created

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