Skip to main content
POST
/
prices
Create price
curl --request POST \
  --url https://api.withorb.com/v1/prices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "<string>",
    "prorated": false
  },
  "name": "<string>",
  "item_id": "<string>",
  "cadence": "annual",
  "currency": "<string>",
  "metadata": {},
  "external_price_id": "<string>",
  "dimensional_price_configuration": {
    "dimension_values": [
      "<string>"
    ],
    "dimensional_price_group_id": "<string>",
    "external_dimensional_price_group_id": "<string>"
  },
  "license_type_id": "<string>",
  "billable_metric_id": "<string>",
  "billed_in_advance": true,
  "fixed_price_quantity": 123,
  "invoice_grouping_key": "<string>",
  "billing_cycle_configuration": {
    "duration": 123,
    "duration_unit": "day"
  },
  "invoicing_cycle_configuration": {
    "duration": 123,
    "duration_unit": "day"
  },
  "conversion_rate": 123,
  "conversion_rate_config": {
    "conversion_rate_type": "unit",
    "unit_config": {
      "unit_amount": "<string>"
    }
  }
}
'
{
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "<string>",
    "prorated": false
  },
  "metadata": {},
  "id": "<string>",
  "name": "<string>",
  "external_price_id": "<string>",
  "replaces_price_id": "<string>",
  "price_type": "usage_price",
  "created_at": "2023-11-07T05:31:56Z",
  "cadence": "one_time",
  "billing_mode": "in_advance",
  "billing_cycle_configuration": {
    "duration": 123,
    "duration_unit": "day"
  },
  "invoicing_cycle_configuration": {
    "duration": 123,
    "duration_unit": "day"
  },
  "billable_metric": {
    "id": "<string>"
  },
  "fixed_price_quantity": 123,
  "plan_phase_order": 123,
  "currency": "<string>",
  "conversion_rate": 123,
  "conversion_rate_config": {
    "conversion_rate_type": "unit",
    "unit_config": {
      "unit_amount": "<string>"
    }
  },
  "item": {
    "id": "<string>",
    "name": "<string>"
  },
  "credit_allocation": {
    "currency": "<string>",
    "allows_rollover": true,
    "custom_expiration": {
      "duration": 123,
      "duration_unit": "day"
    },
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ],
    "license_type_id": "<string>"
  },
  "composite_price_filters": [
    {
      "field": "price_id",
      "operator": "includes",
      "values": [
        "<string>"
      ]
    }
  ],
  "discount": {
    "discount_type": "percentage",
    "percentage_discount": 0.5,
    "applies_to_price_ids": [
      "h74gfhdjvn7ujokd",
      "7hfgtgjnbvc3ujkl"
    ],
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ],
    "reason": "<string>"
  },
  "minimum": {
    "minimum_amount": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ],
    "applies_to_price_ids": [
      "<string>"
    ]
  },
  "minimum_amount": "<string>",
  "maximum": {
    "maximum_amount": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ],
    "applies_to_price_ids": [
      "<string>"
    ]
  },
  "maximum_amount": "<string>",
  "dimensional_price_configuration": {
    "dimensional_price_group_id": "<string>",
    "dimension_values": [
      "<string>"
    ]
  },
  "license_type": {
    "id": "<string>",
    "name": "<string>",
    "grouping_key": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

New floating price request body params.

​
model_type
enum<string>
required

The pricing model type

Available options:
unit
​
unit_config
UnitConfig · object
required

Configuration for unit pricing

​
name
string
required

The name of the price.

Example:

"Annual fee"

​
item_id
string
required

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

​
cadence
enum<string>
required

The cadence to bill for this price on.

Available options:
annual,
semi_annual,
monthly,
quarterly,
one_time,
custom
​
currency
string
required

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

​
metadata
Metadata · object

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.

​
external_price_id
string | null

An alias for the price.

​
dimensional_price_configuration
NewDimensionalPriceConfiguration · object

For dimensional price: specifies a price group and dimension values

​
license_type_id
string | null

The ID of the license type to associate with this price.

​
billable_metric_id
string | null

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

​
billed_in_advance
boolean | null

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 | null

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

​
invoice_grouping_key
string | null

The property used to group this price on an invoice

Minimum string length: 1
​
billing_cycle_configuration
NewBillingCycleConfiguration · object

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

​
invoicing_cycle_configuration
NewBillingCycleConfiguration · object

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

​
conversion_rate
number | null

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

​
conversion_rate_config
UnitConversionRateConfig · object

The configuration for the rate of the price currency to the invoicing currency.

Response

Created

The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill.

Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present.

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

​
model_type
enum<string>
required

The pricing model type

Available options:
unit
​
unit_config
UnitConfig · object
required

Configuration for unit pricing

​
metadata
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.

​
id
string
required
​
name
string
required
​
external_price_id
string | null
required
​
replaces_price_id
string | null
required

The price id this price replaces. This price will take the place of the replaced price in plan version migrations.

​
price_type
enum<string>
required
Available options:
usage_price,
fixed_price,
composite_price
​
created_at
string<date-time>
required
​
cadence
enum<string>
required
Available options:
one_time,
monthly,
quarterly,
semi_annual,
annual,
custom
​
billing_mode
enum<string>
required
Available options:
in_advance,
in_arrear
​
billing_cycle_configuration
BillingCycleConfiguration · object
required
​
invoicing_cycle_configuration
BillingCycleConfiguration · object
required
​
billable_metric
BillableMetricTiny · object
required
​
fixed_price_quantity
number | null
required
​
plan_phase_order
integer | null
required
​
currency
string
required
​
conversion_rate
number | null
required
​
conversion_rate_config
UnitConversionRateConfig · object
required
​
item
ItemSlim · object
required

A minimal representation of an Item containing only the essential identifying information.

​
credit_allocation
Allocation · object
required
​
composite_price_filters
PriceFilter · object[] | null
required
​
discount
PercentageDiscount · object
required
deprecated
​
minimum
Minimum · object
required
deprecated
​
minimum_amount
string | null
required
deprecated
​
maximum
Maximum · object
required
deprecated
​
maximum_amount
string | null
required
deprecated
​
dimensional_price_configuration
DimensionalPriceConfiguration · object
​
license_type
LicenseType · object

The LicenseType resource represents a type of license that can be assigned to users. License types are used during billing by grouping metrics on the configured grouping key.