Prices

Get price by lookup key

Use when resolving a price by external id (e.g. from your catalog or CMS). Ideal for integrations.

get/prices/lookup/{lookup_key}

Path parameters

lookup_keystring required

Lookup key

Response

amountstring

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

billing_cadence'RECURRING'

billing_model'FLAT_FEE' | 'PACKAGE' | 'TIERED'

billing_period_countinteger

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

conversion_ratestring

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

created_atstring date-time

created_bystring

currencystring

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

descriptionstring

Description of the price

display_amountstring

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

display_namestring

DisplayName is the name of the price

display_price_unit_amountstring

DisplayPriceUnitAmount is the formatted amount of the price unit

end_datestring date-time

EndDate is the end date of the price

entity_idstring

EntityID holds the value of the "entity_id" field.

entity_type'PLAN' | 'SUBSCRIPTION' | 'ADDON' | 'PRICE' | 'COSTSHEET'

environment_idstring

EnvironmentID is the environment identifier for the price

group_idstring

GroupID references the group this price belongs to

idstring

ID uuid identifier for the price

invoice_cadence'ARREAR' | 'ADVANCE'

lookup_keystring

LookupKey used for looking up the price in the database

metadataPriceJSONBMetadata

meter_idstring

MeterID is the id of the meter for usage based pricing

min_quantitystring nullable

MinQuantity is the minimum quantity of the price

parent_price_idstring

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

price_unitstring

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

price_unit_amountstring

PriceUnitAmount is the amount of the price unit

price_unit_idstring

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

price_unit_type'FIAT' | 'CUSTOM'

sequenceinteger

Sequence is the monotonic stamp bumped on every state change that subscription line items need to react to. Read by the plan-price sync; set by the database (DEFAULT nextval) on create and by the price repository on termination / compatibility-affecting edits.

start_datestring date-time

StartDate is the start date of the price

status'published' | 'deleted' | 'archived'

tenant_idstring

tier_mode'VOLUME' | 'SLAB'

trial_period_daysinteger

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

type'USAGE' | 'FIXED'

updated_atstring date-time

updated_bystring

Example response

{
  "addon": {
    "entitlements": [
      {
        "feature": {
          "meter": {
            "created_at": "2024-03-20T15:04:05Z",
            "event_name": "api_request",
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "API Usage Meter",
            "status": "published",
            "tenant_id": "tenant123",
            "updated_at": "2024-03-20T15:04:05Z"
          }
        }
      }
    ]
  },
  "meter": {
    "created_at": "2024-03-20T15:04:05Z",
    "event_name": "api_request",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "API Usage Meter",
    "status": "published",
    "tenant_id": "tenant123",
    "updated_at": "2024-03-20T15:04:05Z"
  },
  "plan": {
    "entitlements": [
      {
        "feature": {
          "meter": {
            "created_at": "2024-03-20T15:04:05Z",
            "event_name": "api_request",
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "API Usage Meter",
            "status": "published",
            "tenant_id": "tenant123",
            "updated_at": "2024-03-20T15:04:05Z"
          }
        }
      }
    ]
  }
}

Changes

Changed in 7 of the 12 revisions of this API.1318

Jun 29, 2026cef2964c102c22See the full diff
- ●
  added the new config enum value to the addon/entitlements/items/feature/type response property for the response status 200
  response-property-enum-value-added
- ●
  added the new config enum value to the addon/entitlements/items/feature_type response property for the response status 200
  response-property-enum-value-added
- ○
  added the optional property addon/entitlements/items/config_value to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property sequence to the response with the 200 status
  response-optional-property-added
May 18, 2026f62d8a5fe7cf4See the full diff
- ●
  removed the optional property details from the response with the 400 status
  response-optional-property-removed
- ●
  removed the optional property details from the response with the 500 status
  response-optional-property-removed
- ●
  added the new too_many_requests enum value to the code response property for the response status 400
  response-property-enum-value-added
- ●
  added the new too_many_requests enum value to the code response property for the response status 500
  response-property-enum-value-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 18, 20260cb3425d658021See the full diff
- ●
  removed the optional property addon/type from the response with the 200 status
  response-optional-property-removed
- ●
  added the new ONETIME enum value to the billing_period response property for the response status 200
  response-property-enum-value-added
- ○
  removed the ONETIME enum value from the billing_cadence response property for the response status 200
  response-property-enum-value-removed
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 23, 202682f205e0f42911See the full diff
- ●
  removed the optional property trial_period from the response with the 200 status
  response-optional-property-removed
- ○
  added the optional property trial_period_days to the response with the 200 status
  response-optional-property-added
Apr 6, 20264ded3711f40148See the full diff
- ●
  removed the optional property error from the response with the 400 status
  response-optional-property-removed
- ●
  removed the optional property error from the response with the 500 status
  response-optional-property-removed
- ●
  removed the optional property success from the response with the 400 status
  response-optional-property-removed
- ●
  removed the optional property success from the response with the 500 status
  response-optional-property-removed
- ○
  added the optional property code to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property code to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property http_status_code to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property http_status_code to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property message to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property message to the response with the 500 status
  response-optional-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Mar 20, 2026bc91c95fbb1a5See the full diff
- ○
  added the optional property addon/entitlements/items/feature/group to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property addon/entitlements/items/feature/group_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property addon/entitlements/items/feature/meter/aggregation/expression to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property addon/entitlements/items/feature/reporting_unit to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property meter/aggregation/expression to the response with the 200 status
  response-optional-property-added
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 27, 2026152f346e42411See the full diff
- ○
  endpoint added
  endpoint-added

Full history