# Query product rate plans

Queries product rate plans (PRPs) from the Product Catalog using filters such as plan ID, name, or product ID.  
You can optionally expand related Product Rate Plan Charges (PRPCs) in the response.

Endpoint: POST /commerce/plans/list
Version: 2026-02-20
Security: bearerAuth

## Header parameters:

  - `Accept-Encoding` (string)
    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-Encoding` (string)
    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-Track-Id` (string)
    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 (').

  - `Zuora-Entity-Ids` (string)
    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-Ids` (string)
    Comma separated IDs. If you have Zuora Multi-Org 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.

## Request fields (application/json):

  - `filters` (array, required)
    Filter conditions for querying product rate plans.  
Each filter defines a field, operator, and value.

  - `filters.field` (string, required)
    Field name to filter by, such as prp_id, product_id, or name.
    Example: "prp_id"

  - `filters.operator` (string, required)
    Comparison operator for the filter condition. Supported values:
- EQ  (equals)
- NE  (not equals)
- IN  (in a list of values)
- LIKE (partial match)
- GT  (greater than)
- GTE (greater than or equal)
- LT  (less than)
- LTE (less than or equal)
- SW  (starts with)
- EW  (ends with)
    Enum: "EQ", "NE", "IN", "LIKE", "GT", "GTE", "LT", "LTE", "SW", "EW"

  - `filters.value` (string, required)
    Value to match for the specified field.
    Example: "38660706ef2f48cfb5222f7dde491895"

  - `expand` (object)
    Expand related entities in the response.

  - `expand.product_rate_plan_charges` (boolean)
    Whether to include associated Product Rate Plan Charges (PRPCs).
    Example: true

## Response 200 fields (application/json):

  - `values` (array)
    List of Product Rate Plans returned by the query.

  - `values.id` (string)
    Unique identifier of the Product Rate Plan.
    Example: "38660706ef2f48cfb5222f7dde491895"

  - `values.name` (string)
    Product Rate Plan name.
    Example: "Bronze Plan"

  - `values.description` (string)
    Product Rate Plan description.
    Example: "Basic version of our software service"

  - `values.productId` (string)
    Identifier of the product this plan belongs to.
    Example: "8a90aac8948deebf01949098b7790326"

  - `values.startDate` (string)
    Effective start date of the plan (UTC, YYYY-MM-DD).
    Example: "2025-09-10"

  - `values.endDate` (string)
    Effective end date of the plan (UTC, YYYY-MM-DD).
    Example: "2027-01-01"

  - `values.state` (string)
    Current plan state.
    Example: "active"

  - `values.status` (string)
    Status of the plan.
    Example: "ACTIVE"

  - `values.activeCurrencies` (array)
    Currencies supported by this plan.
    Example: ["USD"]

  - `values.accounting` (object)
    Accounting fields returned by the API. *Type fields are derived from the tenant's chart of accounts and are read-only.

  - `values.accounting.accountingCode` (string)
    An accounting code associated with the charge for reporting or ERP mapping.
Typically a short code or identifier, not the GL account name.
    Example: "PRPC-REV-001"

  - `values.accounting.accountsReceivableAccount` (string)
    Accounts Receivable (AR) account to book invoices for this charge.
Must match an existing account in the tenant's chart of accounts.

  - `values.accounting.accountsReceivableAccountType` (string)
    System-derived type/category of the AR account from the chart of accounts.
Examples include "AccountsReceivable".

  - `values.accounting.adjustmentLiabilityAccount` (string)
    The name of the account where the Account Type is "Adjustment Liability".
    Example: "adjustL-1"

  - `values.accounting.adjustmentLiabilityAccountType` (string)
    System-derived type/category of the Adjustment Liability account from the chart of accounts.
Examples include "AdjustmentLiability".

  - `values.accounting.adjustmentRevenueAccount` (string)
    The name of the account where the Account Type is "Adjustment Revenue".
    Example: "adjustRev-1"

  - `values.accounting.adjustmentRevenueAccountType` (string)
    System-derived type/category of the Adjustment Revenue account from the chart of accounts.
Examples include "AdjustmentRevenue".

  - `values.accounting.contractAssetAccount` (string)
    The name of the account where the Account Type is "Contract Asset".
    Example: "CA-2"

  - `values.accounting.contractAssetAccountType` (string)
    System-derived type/category of the Contract Asset account from the chart of accounts.
    Example: "ContractAsset"

  - `values.accounting.contractLiabilityAccount` (string)
    The name of the account where the Account Type is "Contract Liability".
    Example: "CL-2"

  - `values.accounting.contractLiabilityAccountType` (string)
    System-derived type/category of the Contract Liability account from the chart of accounts.
Examples include "ContractLiability".

  - `values.accounting.contractRecognizedRevenueAccount` (string)
    Recognized revenue account used specifically for contract-based recognition flows.
Must match an existing account in the tenant's chart of accounts.

  - `values.accounting.contractRecognizedRevenueAccountType` (string)
    System-derived type/category of the Contract Recognized Revenue account from the chart of accounts.
    Example: "RecognizedRevenue"

  - `values.accounting.deferredRevenueAccount` (string)
    Deferred revenue (liability) account to book revenue before recognition.
Must match an existing account in the tenant's chart of accounts.

  - `values.accounting.deferredRevenueAccountType` (string)
    System-derived type/category of the Deferred Revenue account from the chart of accounts.
    Example: "DeferredRevenue"

  - `values.accounting.recognizedRevenueAccount` (string)
    The name of the account where the Account Type is "Recognized Revenue".
    Example: "ContractRevRec-1"

  - `values.accounting.recognizedRevenueAccountType` (string)
    System-derived type/category of the Recognized Revenue account from the chart of accounts.
    Example: "RecognizedRevenue"

  - `values.accounting.unbilledReceivablesAccount` (string)
    The name of the account where the Account Type is "Unbilled Receivables".
    Example: "unbilledR-1"

  - `values.accounting.unbilledReceivablesAccountType` (string)
    System-derived type/category of the Unbilled Receivables account from the chart of accounts.
    Example: "UnbilledReceivables"

  - `values.accounting.productRatePlanChargeId` (string)
    The ID of your product rate plan charge.
    Example: "2c92c0f962470b8101624b869fcd45fc"

  - `values.productRatePlanNumber` (string)
    Product Rate Plan number.
    Example: "PRP-00000172"

  - `values.productRatePlanCharges` (array)
    List of Product Rate Plan Charges (PRPCs) belonging to the plan.

  - `values.productRatePlanCharges.id` (string)
    Unique identifier of the Product Rate Plan Charge.
    Example: "fe9b0e764dca4178a11c0e471e5dc0d8"

  - `values.productRatePlanCharges.name` (string)
    Charge name.
    Example: "prepay_currency"

  - `values.productRatePlanCharges.chargeType` (string)
    Charge type (recurring, one_time, or usage).
    Example: "recurring"

  - `values.productRatePlanCharges.chargeModel` (string)
    Charge model (flat_fee, per_unit, tiered, etc.).
    Example: "flat_fee"

  - `values.productRatePlanCharges.listPriceBase` (string)
    Indicates how list price is interpreted.
    Example: "Per_Billing_Period"

  - `values.productRatePlanCharges.specificListPriceBase` (number)
    Optional override for list price base when billing uses a specific period configuration.

  - `values.productRatePlanCharges.triggerEvent` (string)
    Event that triggers the charge.
    Example: "contract_effective"

  - `values.productRatePlanCharges.unitOfMeasure` (string)
    Unit of measure used for pricing (for example, Each).
    Example: "Each"

  - `values.productRatePlanCharges.defaultQuantity` (number)
    Default quantity applied for the charge.
    Example: 1

  - `values.productRatePlanCharges.endDateCondition` (string)
    Condition that determines when the charge ends.
    Example: "subscription_end"

  - `values.productRatePlanCharges.upToPeriodsType` (string)
    Unit applied when charge ends after a fixed duration.
    Example: "billing_periods"

  - `values.productRatePlanCharges.upToPeriods` (number)
    Number of periods defining fixed charge duration.

  - `values.productRatePlanCharges.billCycle` (object)
    Billing cycle configuration.
    Example: {"period":"bill_cycle_period_quarter","periodAlignment":"align_to_term_start","timing":"in_advance","type":"term_start_day"}

  - `values.productRatePlanCharges.pricing` (object)
    Pricing configuration for the charge.
    Example: {"flatAmounts":{"USD":30},"tiers":[]}

  - `values.productRatePlanCharges.pricingSummary` (array)
    Human-readable pricing summary lines.
    Example: ["USD30"]

  - `values.productRatePlanCharges.taxMode` (string)
    Tax mode for this charge.
    Example: "non_taxable"

  - `values.productRatePlanCharges.taxable` (boolean)
    Indicates whether the charge is taxable.

  - `values.productRatePlanCharges.createdById` (string)
    ID of the user who created the charge.
    Example: "8a90a2fd8030ea2e018032b11d3a3f06"

  - `values.productRatePlanCharges.createdTime` (string)
    Timestamp when the charge was created.
    Example: "2025-02-24T01:21:23.000+00:00"

  - `values.productRatePlanCharges.updatedById` (string)
    ID of the user who last updated the charge.
    Example: "8a90a2fd8030ea2e018032b11d3a3f06"

  - `values.productRatePlanCharges.updatedTime` (string)
    Timestamp when the charge was last updated.
    Example: "2025-02-24T01:21:23.000+00:00"

## Response 400 fields (application/json):

  - `processId` (string)
    The ID of the process that handles the operation.

  - `reasons` (array)
    The container of the error code and message. This field is available only if the success field is false.

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

  - `requestId` (string)
    Unique identifier of the request.

  - `success` (boolean)
    Indicates whether the call succeeded.

## Response 401 fields (application/json):

  - `message` (string)
    Error message.

If the error message is "Authentication error", ensure that the Authorization request header contains valid authentication credentials, then retry the request. See [Authentication](https://developer.zuora.com/docs/guides/authentication/) for more information.

If the error message is "Failed to get user info", retry the request.

## Response 500 fields (application/json):

  - `reasons` (array)
    Example: [{"code":"ObjectNotFound","message":"Notification definition with id 6e569e1e05f040eda51a927b140c0ac1 does not exist"}]

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response