Skip to main content

Create price​

This endpoint is used to create a price. A price created using this endpoint is always an add-on, meaning that it’s not associated with a specific plan and can instead be individually added to subscriptions, including subscriptions on different plans.

An external_price_id can be optionally specified as an alias to allow ergonomic interaction with prices in the Orb API.

See the Price resource for the specification of different price model configurations possible in this endpoint.

Request Body required
    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
    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
    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.

Responses

Created

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

    Loading...