Sign in
Commerce

Query a product rate plan charge with Dynamic Pricing

Returns a product rate plan charge (PRPC) by evaluating Dynamic Pricing against the provided attribute values.
If a matching rate-card row is found, its pricing is returned; otherwise, the default charge-level pricing is used (if defined).
This operation can be used to simulate pricing resolution without creating or updating the charge.

post/commerce/charges/query

Headers

Idempotency-Keystring

Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

Accept-Encodingstring

Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

Content-Encodingstring

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Zuora-Entity-Idsstring

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

Zuora-Org-Idsstring

Comma separated IDs. If you have <a href="https://docs.zuora.com/en/zuora-platform/organization-and-entity-management/multi-org/overview-of-multi-org" target="_blank">Zuora Multi-Org</a> enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs.

Zuora-Track-Idstring

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Request body

product_rate_plan_keystring

Unique identifier (key) of the Product Rate Plan (PRP) to query. This can be the PRP ID or the PRP number configured in your system.

evaluation_level'LIST_PRICE' | 'EXTENDED_PRICE'

Controls how pricing is evaluated for the charge. Supported values: - LIST_PRICE: evaluate pricing at the list-price level. - EXTENDED_PRICE: evaluate pricing at the extended-price level. If not specified, the default is LIST_PRICE.

Example request

{
  "product_rate_plan_key": "11dc762a07064ce496af73ff4cfb5614",
  "expand": {
    "product_rate_plan_charges": true
  },
  "attributes": [
    {
      "name": "Age",
      "value": "Liquidity Provider"
    }
  ],
  "evaluation_level": "LIST_PRICE"
}

Response

OK

attributesobject[]

Attribute metadata associated with Dynamic Pricing for this charge.

chargeFunction'charge_function_standard' | 'charge_function_prepayment' | 'charge_function_commitment_true_up' | 'charge_function_drawdown' | 'charge_function_credit_commitment' | 'charge_function_drawdown_and_credit_commitment'

Internal function/category of the charge used by rating.

chargeModelstring

Pricing model that determines how the amount is calculated.

chargeTypestring

Whether the charge recurs, rates usage, or is a one-time fee.

createdByIdstring

User ID that created the charge record.

createdTimestring date-time

Timestamp when the charge record was created.

customFieldsobject

Tenant-specific custom field values on the charge.

endDateConditionstring

Rule for when the charge ends.

upToPeriodsTypestring

Unit used for the fixed period when endDateCondition is fixed_period, for example, billing periods or days.

upToPeriodsinteger

Number of periods, in units of upToPeriodsType, that the charge remains active when endDateCondition is fixed_period.

extendedPriceobject

Calculated extended price details (model-dependent).

idstring

Unique identifier of the product rate plan charge (PRPC).

isChargeLevelMinCommitboolean

Whether a minimum commit is enforced at the charge level.

isCommittedboolean

Indicates if the charge definition is committed/finalized.

labelsobject

Free-form labels/tags attached to the charge.

listPriceBasestring

List price basis, for example, Per Billing Period, Per Month, Per Year.

specificListPriceBaseinteger

The number of months for the list price base of the charge. This field is required when the ListPriceBase field is set to Per Specific Months. The value must be a positive integer between 1 and 120, inclusive.

Notes:

  • This field is available only if you have the Annual List Price feature enabled.
  • To use this field, you must set the X-Zuora-WSDL-Version request header to 129 or later.
  • The value of this field is null if you do not set the value of the ListPriceBase field to Per Specific Months.
mergedRateCardsobject[]

Effective rate-card rows after merges (if any).

namestring

Display name of the charge in the plan.

negotiatedRateCardsobject[]

Customer- or deal-specific rate-card rows applied by negotiation.

netsuiteobject

NetSuite integration attributes mapped for this charge.

ocmJsonByCurrencyobject

Offer/OCM metadata keyed by currency (internal use).

organizationLabelsstring[]

Organization-level labels associated with the charge.

prepaidboolean

Indicates whether the charge is prepaid.

prepaymentUnitType'unit' | 'currency'

Unit type used for the prepayment charge.

priceChangeOptionstring

How price changes are applied across renewals/amendments.

pricingSummarystring[]

Human-readable price summary strings, for example, USD100.

pricingWaterfallsobject

Detailed pricing/waterfall breakdown (if available).

productChargeDefinitionsobject[]

Underlying charge definitions referenced for pricing lookup.

productRatePlanChargeNumberstring

PRPC number.

productRatePlanIdstring

ID of the plan (PRP) that owns this charge.

prorationOptionstring

How proration is handled relative to tenant defaults.

rateCardsobject[]

Dynamic Pricing rate-card rows configured on the charge.

taxCodestring

Tax code applied to the charge (for example, a tax category code).

taxModestring

Tax mode for the charge.

taxableboolean

Whether the charge is taxable.

triggerEventstring

Event that triggers the charge.

unitOfMeasurestring

Unit of measure used for pricing (for example, Each, Seats).

updatedByIdstring

User ID that last updated the charge record.

updatedTimestring date-time

Timestamp when the charge record was last updated.

useTenantDefaultForPriceChangeboolean

Whether tenant defaults govern price change behavior.

Example response

{
  "accounting": {
    "accountsReceivableAccount": "Accounts Receivable",
    "accountsReceivableAccountType": "AccountsReceivable",
    "deferredRevenueAccount": "Accounts Receivable",
    "deferredRevenueAccountType": "AccountsReceivable",
    "recognizedRevenueAccount": "Accounts Receivable",
    "recognizedRevenueAccountType": "AccountsReceivable"
  },
  "attributes": [],
  "billCycle": {
    "dayOfMonth": 5,
    "period": "bill_cycle_period_month",
    "periodAlignment": "align_to_charge",
    "timing": "in_advance",
    "type": "specific_day_of_month"
  },
  "chargeModel": "flat_fee",
  "chargeType": "recurring",
  "createdById": "53c162482f054f3ca08e1ec82dccfec9",
  "createdTime": "2025-10-13T07:46:02.000+00:00",
  "customFields": {},
  "discountOptions": {
    "applyDetails": [],
    "applyTo": [],
    "applyToBillingPeriodPartially": false,
    "reflectDiscountInNetAmount": false,
    "rollover": false,
    "stackedDiscount": false
  },
  "endDateCondition": "subscription_end",
  "upToPeriodsType": "billing_periods",
  "upToPeriods": 0,
  "extendedPrice": {},
  "id": "ad95b694d2b8442b84dc8ad26561c7d7",
  "isChargeLevelMinCommit": false,
  "isCommitted": false,
  "labels": {},
  "listPriceBase": "Per_Billing_Period",
  "mergedRateCards": [],
  "name": "Flat PRPC 1",
  "negotiatedRateCards": [],
  "netsuite": {},
  "ocmJsonByCurrency": {},
  "organizationLabels": [],
  "overageOptions": {
    "includedUnits": 0,
    "unusedUnitsCreditRates": {}
  },
  "prepaid": true,
  "chargeFunction": "charge_function_prepayment",
  "prepaymentUnitType": "unit",
  "prepayment": {
    "creditOption": "time_based",
    "operationType": "prepaid_operation_type_topup",
    "quantity": 10,
    "rollover": true,
    "rolloverApply": "apply_first",
    "rolloverPeriodLength": 6,
    "rolloverPeriods": 1,
    "unitOfMeasure": "Each",
    "validityPeriod": "specific_months",
    "validityPeriodAlignment": "vp_alignment_term_end",
    "validityPeriodProrationOption": "vp_proration_option_prorate_units",
    "specificValidityPeriodLength": 6,
    "rolloverPeriodType": "rollover_period_type_month",
    "rolloverFundPriority": 2,
    "rolloverEndDateType": "rollover_end_date_type_charge_end_date",
    "fundSupportAccountHierarchy": true,
    "drawdownPriority": 5,
    "drawdownScope": "commitment_level_account"
  },
  "priceChangeOption": "no_change",
  "pricing": {
    "adjustments": {},
    "discountAmounts": {},
    "discountPercentages": {},
    "flatAmounts": {
      "USD": 100
    },
    "maxAmounts": {},
    "minAmounts": {},
    "percentages": {},
    "tiers": [],
    "unitAmounts": {}
  },
  "pricingSummary": [
    "USD100"
  ],
  "pricingWaterfalls": {},
  "productChargeDefinitions": [],
  "productRatePlanChargeNumber": "PRPC-00000279",
  "productRatePlanId": "ee2d1ce1036c4dd6ae9d6945565ff7a0",
  "prorationOption": "default_from_tenant_setting",
  "rateCards": [],
  "revenue": {
    "excludeItemBillingFromRevenueAccounting": false,
    "excludeItemBookingFromRevenueAccounting": false,
    "legacyReporting": false,
    "revenueRecognitionRuleName": "Recognize upon invoicing"
  },
  "taxCode": "TAX_EXEMPT",
  "taxMode": "non_taxable",
  "taxable": false,
  "triggerEvent": "contract_effective",
  "unitOfMeasure": "Each",
  "updatedById": "53c162482f054f3ca08e1ec82dccfec9",
  "updatedTime": "2025-10-13T07:46:02.000+00:00",
  "useTenantDefaultForPriceChange": true
}

Changes