Create price

Use when adding a new price to a plan or catalog (e.g. per-seat, flat, or metered). Ideal for both simple and usage-based pricing.

POST /prices

Create price

cURL

curl --request POST \
  --url https://us.api.flexprice.io/v1/prices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "billing_cadence": "RECURRING",
  "billing_model": "FLAT_FEE",
  "billing_period": "MONTHLY",
  "currency": "<string>",
  "entity_id": "<string>",
  "entity_type": "PLAN",
  "invoice_cadence": "ARREAR",
  "price_unit_type": "FIAT",
  "type": "USAGE",
  "amount": "<string>",
  "billing_period_count": 123,
  "description": "<string>",
  "display_name": "<string>",
  "end_date": "<string>",
  "filter_values": {},
  "group_id": "<string>",
  "lookup_key": "<string>",
  "metadata": {},
  "meter_id": "<string>",
  "min_quantity": 123,
  "start_date": "<string>",
  "tier_mode": "VOLUME",
  "tiers": [
    {
      "unit_amount": "<string>",
      "flat_amount": "<string>",
      "up_to": 123
    }
  ],
  "transform_quantity": {
    "divide_by": 123,
    "round": "up"
  },
  "trial_period": 123
}
'

201

{
  "addon": {
    "created_at": "<string>",
    "created_by": "<string>",
    "description": "<string>",
    "entitlements": [
      {
        "addon": "<unknown>",
        "created_at": "<string>",
        "created_by": "<string>",
        "display_order": 123,
        "end_date": "<string>",
        "entity_id": "<string>",
        "entity_type": "PLAN",
        "environment_id": "<string>",
        "feature": {
          "alert_settings": {
            "alert_enabled": true,
            "critical": {
              "condition": "above",
              "threshold": 123
            },
            "info": {
              "condition": "above",
              "threshold": 123
            },
            "warning": {
              "condition": "above",
              "threshold": 123
            }
          },
          "created_at": "<string>",
          "created_by": "<string>",
          "description": "<string>",
          "environment_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "meter": {
            "aggregation": {
              "bucket_size": "MINUTE",
              "expression": "<string>",
              "field": "<string>",
              "group_by": "<string>",
              "multiplier": "<string>",
              "type": "COUNT"
            },
            "created_at": "2024-03-20T15:04:05Z",
            "event_name": "api_request",
            "filters": [
              {
                "key": "<string>",
                "values": [
                  "<string>"
                ]
              }
            ],
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "API Usage Meter",
            "reset_usage": "BILLING_PERIOD",
            "status": "published",
            "tenant_id": "tenant123",
            "updated_at": "2024-03-20T15:04:05Z"
          },
          "meter_id": "<string>",
          "name": "<string>",
          "status": "published",
          "tenant_id": "<string>",
          "type": "metered",
          "unit_plural": "<string>",
          "unit_singular": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "feature_id": "<string>",
        "feature_type": "metered",
        "id": "<string>",
        "is_enabled": true,
        "is_soft_limit": true,
        "parent_entitlement_id": "<string>",
        "plan": {
          "created_at": "<string>",
          "created_by": "<string>",
          "credit_grants": [
            {
              "cadence": "ONETIME",
              "conversion_rate": "<string>",
              "created_at": "<string>",
              "created_by": "<string>",
              "credit_grant_anchor": "<string>",
              "credits": "<string>",
              "end_date": "<string>",
              "environment_id": "<string>",
              "expiration_duration": 123,
              "expiration_duration_unit": "DAY",
              "expiration_type": "NEVER",
              "id": "<string>",
              "metadata": {},
              "name": "<string>",
              "period": "DAILY",
              "period_count": 123,
              "plan_id": "<string>",
              "priority": 123,
              "scope": "PLAN",
              "start_date": "<string>",
              "status": "published",
              "subscription_id": "<string>",
              "tenant_id": "<string>",
              "topup_conversion_rate": "<string>",
              "updated_at": "<string>",
              "updated_by": "<string>"
            }
          ],
          "description": "<string>",
          "display_order": 123,
          "entitlements": "<array>",
          "environment_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "name": "<string>",
          "prices": "<array>",
          "status": "published",
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "plan_id": "<string>",
        "start_date": "<string>",
        "static_value": "<string>",
        "status": "published",
        "tenant_id": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>",
        "usage_limit": 123,
        "usage_reset_period": "MONTHLY"
      }
    ],
    "environment_id": "<string>",
    "id": "<string>",
    "lookup_key": "<string>",
    "metadata": {},
    "name": "<string>",
    "prices": "<array>",
    "status": "published",
    "tenant_id": "<string>",
    "type": "onetime",
    "updated_at": "<string>",
    "updated_by": "<string>"
  },
  "amount": "<string>",
  "billing_cadence": "RECURRING",
  "billing_model": "FLAT_FEE",
  "billing_period": "MONTHLY",
  "billing_period_count": 123,
  "conversion_rate": "<string>",
  "created_at": "<string>",
  "created_by": "<string>",
  "currency": "<string>",
  "description": "<string>",
  "display_amount": "<string>",
  "display_name": "<string>",
  "display_price_unit_amount": "<string>",
  "end_date": "<string>",
  "entity_id": "<string>",
  "entity_type": "PLAN",
  "environment_id": "<string>",
  "group": {
    "created_at": "<string>",
    "entity_ids": [
      "<string>"
    ],
    "entity_type": "<string>",
    "id": "<string>",
    "lookup_key": "<string>",
    "metadata": {},
    "name": "<string>",
    "status": "<string>",
    "updated_at": "<string>"
  },
  "group_id": "<string>",
  "id": "<string>",
  "invoice_cadence": "ARREAR",
  "lookup_key": "<string>",
  "metadata": {},
  "meter": {
    "aggregation": {
      "bucket_size": "MINUTE",
      "expression": "<string>",
      "field": "<string>",
      "group_by": "<string>",
      "multiplier": "<string>",
      "type": "COUNT"
    },
    "created_at": "2024-03-20T15:04:05Z",
    "event_name": "api_request",
    "filters": [
      {
        "key": "<string>",
        "values": [
          "<string>"
        ]
      }
    ],
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "API Usage Meter",
    "reset_usage": "BILLING_PERIOD",
    "status": "published",
    "tenant_id": "tenant123",
    "updated_at": "2024-03-20T15:04:05Z"
  },
  "meter_id": "<string>",
  "min_quantity": "<string>",
  "parent_price_id": "<string>",
  "plan": {
    "created_at": "<string>",
    "created_by": "<string>",
    "credit_grants": [
      {
        "cadence": "ONETIME",
        "conversion_rate": "<string>",
        "created_at": "<string>",
        "created_by": "<string>",
        "credit_grant_anchor": "<string>",
        "credits": "<string>",
        "end_date": "<string>",
        "environment_id": "<string>",
        "expiration_duration": 123,
        "expiration_duration_unit": "DAY",
        "expiration_type": "NEVER",
        "id": "<string>",
        "metadata": {},
        "name": "<string>",
        "period": "DAILY",
        "period_count": 123,
        "plan_id": "<string>",
        "priority": 123,
        "scope": "PLAN",
        "start_date": "<string>",
        "status": "published",
        "subscription_id": "<string>",
        "tenant_id": "<string>",
        "topup_conversion_rate": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>"
      }
    ],
    "description": "<string>",
    "display_order": 123,
    "entitlements": "<array>",
    "environment_id": "<string>",
    "id": "<string>",
    "lookup_key": "<string>",
    "metadata": {},
    "name": "<string>",
    "prices": "<array>",
    "status": "published",
    "tenant_id": "<string>",
    "updated_at": "<string>",
    "updated_by": "<string>"
  },
  "price_unit": "<string>",
  "price_unit_amount": "<string>",
  "price_unit_id": "<string>",
  "price_unit_tiers": [
    {
      "flat_amount": "<string>",
      "unit_amount": "<string>",
      "up_to": 123
    }
  ],
  "price_unit_type": "FIAT",
  "pricing_unit": {
    "base_currency": "<string>",
    "code": "<string>",
    "conversion_rate": "<string>",
    "created_at": "<string>",
    "created_by": "<string>",
    "environment_id": "<string>",
    "id": "<string>",
    "metadata": {},
    "name": "<string>",
    "status": "published",
    "symbol": "<string>",
    "tenant_id": "<string>",
    "updated_at": "<string>",
    "updated_by": "<string>"
  },
  "start_date": "<string>",
  "status": "published",
  "tenant_id": "<string>",
  "tier_mode": "VOLUME",
  "tiers": [
    {
      "flat_amount": "<string>",
      "unit_amount": "<string>",
      "up_to": 123
    }
  ],
  "transform_quantity": {
    "divide_by": 123,
    "round": "up"
  },
  "trial_period": 123,
  "type": "USAGE",
  "updated_at": "<string>",
  "updated_by": "<string>"
}

Authorizations

x-api-key · string · header · required

Enter your API key in the format x-api-key <api-key>*

Body

application/json

Price configuration

billing_cadence · enum<string> · required

Available options: RECURRING, ONETIME

billing_model · enum<string> · required

Available options: FLAT_FEE, PACKAGE, TIERED

billing_period · enum<string> · required

Available options: MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY

currency · string · required

entity_id · string · required

entity_type · enum<string> · required

Available options: PLAN, SUBSCRIPTION, ADDON, PRICE, COSTSHEET

invoice_cadence · enum<string> · required

Available options: ARREAR, ADVANCE

price_unit_type · enum<string> · required

Available options: FIAT, CUSTOM

type · enum<string> · required

Available options: USAGE, FIXED

amount · string

billing_period_count · integer

description · string

display_name · string

end_date · string

filter_values · object

Show child attributes

group_id · string

GroupID is the id of the group to add the price to

lookup_key · string

metadata · object

Show child attributes

meter_id · string

min_quantity · integer

MinQuantity is the minimum quantity of the price

price_unit_config · object

Show child attributes

start_date · string

tier_mode · enum<string>

Available options: VOLUME, SLAB

tiers · object[]

Show child attributes

transform_quantity · object

Show child attributes

trial_period · integer

Response

201

application/json

Created

addon · object

Show child attributes

amount · string

Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50

billing_cadence · enum<string>

Available options: RECURRING, ONETIME

billing_model · enum<string>

Available options: FLAT_FEE, PACKAGE, TIERED

billing_period · enum<string>

Available options: MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY

billing_period_count · integer

BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12

conversion_rate · string

ConversionRate is the conversion rate of the price unit to the fiat currency

created_at · string

created_by · string

currency · string

Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp

description · string

Description of the price

display_amount · string

DisplayAmount is the formatted amount with currency symbol For USD: $12.50

display_name · string

DisplayName is the name of the price

display_price_unit_amount · string

DisplayPriceUnitAmount is the formatted amount of the price unit

end_date · string

EndDate is the end date of the price

entity_id · string

EntityID holds the value of the "entity_id" field.

entity_type · enum<string>

Available options: PLAN, SUBSCRIPTION, ADDON, PRICE, COSTSHEET

environment_id · string

EnvironmentID is the environment identifier for the price

group · object

Show child attributes

group_id · string

GroupID references the group this price belongs to

id · string

ID uuid identifier for the price

invoice_cadence · enum<string>

Available options: ARREAR, ADVANCE

lookup_key · string

LookupKey used for looking up the price in the database

metadata · object

Show child attributes

meter · object

Show child attributes

meter_id · string

MeterID is the id of the meter for usage based pricing

min_quantity · string | null

MinQuantity is the minimum quantity of the price

parent_price_id · string

ParentPriceID references the root price (always set for price lineage tracking)

plan · object

Show child attributes

price_unit · string

PriceUnit is the code of the price unit (e.g., 'btc', 'eth')

price_unit_amount · string

PriceUnitAmount is the amount of the price unit

price_unit_id · string

PriceUnitID is the id of the price unit (for CUSTOM type)

price_unit_tiers · object[]

PriceUnitTiers are the tiers for the price unit when BillingModel is TIERED

Show child attributes

price_unit_type · enum<string>

Available options: FIAT, CUSTOM

pricing_unit · object

Show child attributes

start_date · string

StartDate is the start date of the price

status · enum<string>

Available options: published, deleted, archived

tenant_id · string

tier_mode · enum<string>

Available options: VOLUME, SLAB

tiers · object[]

Show child attributes

transform_quantity · object

Show child attributes

trial_period · integer

TrialPeriod is the number of days for the trial period Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING)

type · enum<string>

Available options: USAGE, FIXED

updated_at · string

updated_by · string