Update

PATCH /v0/prices/{id}

Update

cURL

curl --request PATCH \
  --url https://api.paygentic.io/v0/prices/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "billableMetricId": "<string>",
  "pricingUnitId": "<string>",
  "invoiceDisplayName": "<string>",
  "invoiceDisplayGroup": "<string>",
  "invoiceRateLabel": "<string>",
  "properties": {
    "unitPrice": "<string>"
  },
  "billingCadence": "<string>",
  "feature": {
    "featureId": "<string>",
    "entitlementTemplate": {}
  },
  "grantDiscountEnabled": true,
  "isObligation": true,
  "quantity": 1
}
'

200

{
  "id": "price_r7s8t9u0v1w2x3y4",
  "object": "price",
  "billableMetricId": "bm_z5a6b7c8d9e0f1g2",
  "createdAt": "2024-01-25T10:00:00Z",
  "currency": "USD",
  "description": "Per-call pricing for ML inference",
  "invoiceDisplayName": "Inference API Calls",
  "model": "standard",
  "paymentTerm": "in_arrears",
  "properties": {
    "unitPrice": "0.05"
  },
  "unitAmount": "50000000",
  "updatedAt": "2024-03-05T14:20:00Z"
}

Authorizations

Authorization · string · header · required

API key authentication

Path Parameters

id · string · required

The unique identifier of the price Unique identifier for a price

Pattern: ^price_[a-zA-Z0-9]+$

Body

application/json

billableMetricId · string

The unique identifier for the billable metric referred to by this price.

Pattern: ^bm_[a-zA-Z0-9]+$

pricingUnitId · string | null

Denominate this metered price in a pricing unit (credits). Set to a pricing unit ID to draw down a credit pool, null to revert to real currency, or omit to leave unchanged.

Pattern: ^pu_[a-zA-Z0-9]+$

invoiceDisplayName · string

Updated invoice line item label. Sample values: 'LLM Token Usage', 'Storage Charges', 'API Call Fees'

invoiceDisplayGroup · string | null

Presentation only. Prices sharing this value, within one billing period, print as a single row on the rendered invoice PDF and are described by this string. Every member still bills its own line item on the ledger, this API and the compliance document. Requires invoiceRateLabel. Sample values: 'Cross Border Fees', 'FX Fees'

invoiceRateLabel · string | null

This price's contribution to the combined row's rate cell, joined with ' + ' across the group. Only read for a price that sets invoiceDisplayGroup. Sample values: '1.00%', '0.30 GBP', '2.5%'

model · enum<string>

The pricing model to set. 'standard' and 'volume' are accepted. Legacy 'dynamic'/'percentage' prices can still be edited (other fields) but cannot be switched back to those models. Percentage/revenue-share is expressed via 'standard' with a unit-price multiplier.

Available options: standard, volume

properties · StandardPriceProperties · object

Standard pricing model

StandardPriceProperties

DynamicPriceProperties

VolumePriceProperties

PercentagePriceProperties

Show child attributes

paymentTerm · enum<string>

Billing timing preference: 'in_advance' (prepaid — charged upfront or drawn from a prepaid commitment) or 'in_arrears' (charged at period end).

Available options: in_arrears, in_advance

billingCadence · string | null

ISO 8601 duration for recurring fees (e.g., 'P1M' for monthly, 'P1Y' for yearly, or 'P0D' for one-time)

feature · object | null

Feature to associate. Set to null to remove existing feature. Omit to leave unchanged.

Show child attributes

grantDiscountEnabled · boolean

When true, grants applied to a subscription will discount usage charged by this price. Only supported for standard metered prices.

isObligation · boolean

A fixed amount owed whole rather than a per-period rate. An obligation is not prorated over a partial first period: when a subscription starts before its billing anchor, no truncated stub is billed and the first charge is the full amount at the next anchor. An obligation also refuses an interval boundary that falls strictly inside one of its own billing periods, since part of an amount owed whole is not a thing to bill. Defaults to false, which is a rate and is today's behaviour for every price. Not supported on a metered price, whose amount resolves from usage at close.

quantity · integer

Quantity for invoice line items. Total per period = quantity × unitPrice. Only supported for fee prices; metered prices derive quantity from usage. Defaults to 1.

Required range: x >= 0

Response

200

application/json

Price updated successfully

id · string · required

Unique identifier for a price

Pattern: ^price_[a-zA-Z0-9]+$

object · enum<string> · default: price · required

Available options: price

merchantId · string · required

The merchant organization that owns this price, derived from the associated fee or billable metric. Present on single-price reads.

Pattern: ^org_[a-zA-Z0-9]+$

createdAt · string<date-time> · required

invoiceDisplayName · string · required

paymentTerm · enum<string> · required

Available options: in_arrears, in_advance

properties · StandardPriceProperties · object · required

Standard pricing model

StandardPriceProperties

DynamicPriceProperties

VolumePriceProperties

PercentagePriceProperties

Show child attributes

updatedAt · string<date-time> · required

quantity · integer · required

Quantity for invoice line items. Total per period = quantity × unitPrice. Only supported for fee prices; metered prices derive quantity from usage. Defaults to 1.

Required range: x >= 0

billableMetricId · string

Unique identifier for a billable metric

Pattern: ^bm_[a-zA-Z0-9]+$

feeId · string

The unique identifier for the fee referred to by this price. Present when price is linked to a fee.

Pattern: ^fee_[a-zA-Z0-9]+$

pricingUnitId · string

The pricing unit this price is denominated in (credits). Present when the price draws down a credit pool instead of charging real currency.

Pattern: ^pu_[a-zA-Z0-9]+$

billingCadence · string | null

ISO 8601 duration. 'P0D' for one-time, 'P1M' for monthly, 'P1Y' for yearly. Required for fees, optional for billable metrics. Defaults to plan's billingCadence if not specified.

invoiceDisplayGroup · string | null

Presentation only. Prices sharing this value, within one billing period, print as a single row on the rendered invoice PDF and are described by this string. Every member still bills its own line item on the ledger, this API and the compliance document. Requires invoiceRateLabel. Sample values: 'Cross Border Fees', 'FX Fees'

invoiceRateLabel · string | null

This price's contribution to the combined row's rate cell, joined with ' + ' across the group. Only read for a price that sets invoiceDisplayGroup. Sample values: '1.00%', '0.30 GBP', '2.5%'

model · enum<string>

Pricing model of a price as returned by the API. Includes the legacy models ('dynamic', 'percentage') retained for existing prices; 'standard' and 'volume' can be created (see PriceModelInput).

Available options: standard, dynamic, volume, percentage

features · object[]

Features associated with this price

Show child attributes

grantDiscountEnabled · boolean · default: false

When true, grants applied to a subscription will discount usage charged by this price. Only supported for standard metered prices.

isObligation · boolean · default: false

A fixed amount owed whole rather than a per-period rate. An obligation is not prorated over a partial first period: when a subscription starts before its billing anchor, no truncated stub is billed and the first charge is the full amount at the next anchor. An obligation also refuses an interval boundary that falls strictly inside one of its own billing periods, since part of an amount owed whole is not a thing to bill. Defaults to false, which is a rate and is today's behaviour for every price. Not supported on a metered price, whose amount resolves from usage at close.