Skip to main content
Represents a price configuration for a plan or addon. Prices define how much customers pay based on billing model, period, and optional tiers.

​
Type Definition

type Price {
  id: UUID!

  # Billing configuration
  billingModel: BillingModel!
  billingPeriod: BillingPeriod!
  billingCadence: BillingCadence!
  billingCountryCode: String
  billingId: String

  # Price amount
  price: Money
  blockSize: Float
  minUnitQuantity: Float
  maxUnitQuantity: Float

  # Tiered pricing
  tiers: [PriceTier!]
  tiersMode: TiersMode

  # Feature association
  feature: Feature
  featureId: String

  # Reset period
  resetPeriod: EntitlementResetPeriod
  resetPeriodConfiguration: ResetPeriodConfiguration

  # Credit rate
  creditRate: CreditRate
  creditGrantCadence: CreditGrantCadence

  # Custom currency
  customCurrency: CustomCurrency
  topUpCustomCurrencyId: UUID

  # Package association
  package: PackageDTO!
  packageId: String

  # Metadata
  isOverridePrice: Boolean!
  usedInSubscriptions: Boolean
  crmId: String
  crmLinkUrl: String

  # Timestamps
  createdAt: DateTime
  environmentId: String
}

​
Fields

​
Billing Configuration

FieldTypeDescription
billingModelBillingModel!How usage is calculated (FLAT_FEE, PER_UNIT, USAGE_BASED, etc.)
billingPeriodBillingPeriod!Billing frequency (MONTHLY, ANNUALLY)
billingCadenceBillingCadence!When to bill (IN_ADVANCE, IN_ARREARS)
billingCountryCodeStringCountry code for regional pricing
billingIdStringID in the billing provider

​
Price Amount

FieldTypeDescription
priceMoneyThe price amount with currency
blockSizeFloatNumber of units per block (for block pricing)
minUnitQuantityFloatMinimum billable units
maxUnitQuantityFloatMaximum billable units

​
Tiered Pricing

FieldTypeDescription
tiers[PriceTier!]Pricing tiers for tiered billing
tiersModeTiersModeHow tiers are applied (VOLUME, GRADUATED)

​
Feature Association

FieldTypeDescription
featureFeatureThe feature this price applies to (for usage-based)
featureIdStringFeature identifier

​
Reset Period

FieldTypeDescription
resetPeriodEntitlementResetPeriodWhen usage resets
resetPeriodConfigurationResetPeriodConfigurationDetailed reset settings

​
Credit Rate

FieldTypeDescription
creditRateCreditRateCredit rate for credit-based pricing
creditGrantCadenceCreditGrantCadenceWhen credits are granted

​
BillingModel Enum

ValueDescription
FLAT_FEEFixed price regardless of usage
PER_UNITPrice per unit (e.g., per seat)
USAGE_BASEDPrice based on metered usage
CREDIT_BASEDPrice based on credit consumption
MINIMUM_SPENDMinimum spend commitment

​
BillingPeriod Enum

ValueDescription
MONTHLYBilled monthly
ANNUALLYBilled annually

​
BillingCadence Enum

ValueDescription
IN_ADVANCEBilled at the start of the period
IN_ARREARSBilled at the end of the period

​
TiersMode Enum

ValueDescription
VOLUMEAll units are charged at the tier rate
GRADUATEDEach tier has its own rate

​
PriceTier Type

type PriceTier {
  upTo: Float
  unitPrice: Money
  flatPrice: Money
}
FieldTypeDescription
upToFloatUpper limit of this tier (null = unlimited)
unitPriceMoneyPrice per unit in this tier
flatPriceMoneyFlat price for this tier

​
Money Type

type Money {
  amount: Float!
  currency: Currency!
}

​
Example Response

​
Flat Fee Price

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "billingModel": "FLAT_FEE",
  "billingPeriod": "MONTHLY",
  "billingCadence": "IN_ADVANCE",
  "price": {
    "amount": 99.00,
    "currency": "USD"
  },
  "isOverridePrice": false,
  "createdAt": "2024-01-10T10:00:00Z"
}

​
Per Unit Price

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "billingModel": "PER_UNIT",
  "billingPeriod": "MONTHLY",
  "billingCadence": "IN_ADVANCE",
  "price": {
    "amount": 10.00,
    "currency": "USD"
  },
  "minUnitQuantity": 1,
  "maxUnitQuantity": 100,
  "feature": {
    "refId": "feature-seats",
    "displayName": "Team Seats"
  },
  "isOverridePrice": false
}

​
Usage-Based Price (Tiered)

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "billingModel": "USAGE_BASED",
  "billingPeriod": "MONTHLY",
  "billingCadence": "IN_ARREARS",
  "tiersMode": "GRADUATED",
  "tiers": [
    {
      "upTo": 1000,
      "unitPrice": {
        "amount": 0.01,
        "currency": "USD"
      }
    },
    {
      "upTo": 10000,
      "unitPrice": {
        "amount": 0.008,
        "currency": "USD"
      }
    },
    {
      "upTo": null,
      "unitPrice": {
        "amount": 0.005,
        "currency": "USD"
      }
    }
  ],
  "feature": {
    "refId": "feature-api-calls",
    "displayName": "API Calls"
  },
  "resetPeriod": "MONTH",
  "isOverridePrice": false
}

​
Credit-Based Price

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "billingModel": "CREDIT_BASED",
  "billingPeriod": "MONTHLY",
  "billingCadence": "IN_ADVANCE",
  "creditRate": {
    "amount": 100,
    "customCurrency": {
      "name": "API Credits",
      "symbol": "credits"
    }
  },
  "creditGrantCadence": "BEGINNING_OF_BILLING_PERIOD",
  "feature": {
    "refId": "feature-api-credits",
    "displayName": "API Credits"
  },
  "isOverridePrice": false
}