# Query purchase options by PRP ID

Retrieves one or more product rate plans (PRPs) from the Product Catalog based on specified filters such as product ID or PRP ID.
You can optionally expand related product rate plan charges (PRPCs) in the response.

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

## Header parameters:

  - `Idempotency-Key` (string)
    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-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-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.

  - `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-Version` (string)
    The minor API version.

For a list of available minor versions, see API upgrades.

## Query parameters:

  - `rejectUnknownFields` (boolean)
    Specifies whether the call fails if the request body contains unknown fields.
With rejectUnknownFields set to true, Zuora returns a 400 response if
the request body contains unknown fields. The body of the 400 response is:

json
{
    "message": "Error - unrecognised fields"
}


By default, Zuora ignores unknown fields in the request body.

## Request fields (application/json):

  - `filters` (array)
    Defines the filtering criteria for querying purchase options or product rate plans.
Each filter includes a target field, an operator, and a value.

  - `filters.field` (string, required)
    Name of the field to filter by.
Supported fields include:
  - prp_id: Product Rate Plan ID.
  - product_id: Product ID.
    Example: "prp_id"

  - `filters.operator` (string, required)
    Comparison operator. Supported values:
- EQ  (equals)
- NE  (not equals)
- LT  (less than)
- GT  (greater than)
- SW  (starts with)
- EW  (ends with)
- IN  (in list)
- LIKE (partial match)
    Enum: "EQ", "NE", "LT", "GT", "SW", "IN", "EW", "LIKE"

  - `filters.value` (object, required)
    Specifies the value to compare against.
Only one of the following value types should be provided.

  - `filters.value.string_value` (string)
    String value for string-based comparisons.
    Example: "8a90f5088799c8ed01879cb4b47a3b1a"

  - `filters.value.number_value` (number)
    Numeric value for numeric comparisons.

  - `filters.value.boolean_value` (boolean)
    Boolean value for logical comparisons.

  - `expand` (object)
    Optional flags to include related entities in the query results.

  - `expand.product_rate_plan_charges` (boolean)
    When true, expands the response to include Product Rate Plan Charges (PRPCs)
associated with the queried Product Rate Plans. Expanded PRPCs include full
charge configuration, including pricing, billing settings, and end date
configuration fields such as endDateCondition, upToPeriodsType, and upToPeriods.
    Example: true

  - `product_rate_plan_charge_key` (string)
    Optional identifier for a specific Product Rate Plan Charge (PRPC) to query.
Can be either a PRPC ID or a PRPC number/key.
    Example: "ad95b694d2b8442b84dc8ad26561c7d7"

  - `attributes` (array)
    Optional attributes used for evaluating Dynamic Pricing.
Required when the queried PRPC is configured to depend on contextual attributes.

  - `attributes.name` (string, required)
    Name of the pricing attribute (e.g., Region, Age, EffectiveDate).
    Example: "Region"

  - `attributes.string_value` (string)
    String-based attribute value.

  - `attributes.number_value` (number)
    Numeric attribute value.

  - `attributes.boolean_value` (boolean)
    Boolean attribute value.

  - `attributes.date_value` (string)
    Date value in YYYY-MM-DD format.

  - `attributes.datetime_value` (string)
    Datetime value in ISO 8601 format.

## Response 200 fields (application/json):

  - `error` (object,null)
    Error information, if the request fails. Returns null on success.

  - `productRatePlans` (array)
    List of Product Rate Plans (PRPs) that match the filter criteria.
Each PRP includes associated product, pricing, and charge configuration details.
    Example: [{"id":"8a90f5088799c8ed01879cb4b47a3b1a","name":"New Rate Plan","state":"active","productId":"8a90f5088799c8ed01879cb481d83b18","productRatePlanCharges":[{"id":"8a90876c8799b81801879cb516f8400b","name":"New Component","chargeType":"recurring","chargeModel":"flat_fee","pricing":{"flatAmounts":{"USD":100}},"pricingSummary":["USD100"],"taxMode":"tax_exclusive","taxable":true,"triggerEvent":"contract_effective","endDateCondition":"subscription_end","upToPeriodsType":"billing_periods","upToPeriods":0,"createdTime":"2023-04-19T20:28:46.000+00:00","updatedTime":"2023-04-19T20:28:46.000+00:00"}]}]

  - `productRatePlans.id` (string)
    Unique identifier of the Product Rate Plan (PRP).
    Example: "8a90f5088799c8ed01879cb4b47a3b1a"

  - `productRatePlans.name` (string)
    Display name of the Product Rate Plan.
    Example: "New Rate Plan"

  - `productRatePlans.description` (string)
    Description of the Product Rate Plan.

  - `productRatePlans.startDate` (string)
    Effective start date of the Product Rate Plan.

  - `productRatePlans.endDate` (string)
    Effective end date of the Product Rate Plan.

  - `productRatePlans.state` (string)
    Current state of the Product Rate Plan (for example, active).
    Example: "active"

  - `productRatePlans.productRatePlanNumber` (string)
    Unique reference number of the Product Rate Plan.
    Example: "PRP-00000001"

  - `productRatePlans.productId` (string)
    ID of the Product associated with this rate plan.
    Example: "8a90f5088799c8ed01879cb481d83b18"

  - `productRatePlans.product` (object)
    Metadata and configuration details for the associated Product.

  - `productRatePlans.product.id` (string)
    Unique Product ID.

  - `productRatePlans.product.name` (string)
    Product name.

  - `productRatePlans.product.productNumber` (string)
    Unique product reference number.

  - `productRatePlans.product.category` (string)
    Product category, such as base or addon.

  - `productRatePlans.product.sku` (string)
    Stock-keeping unit (SKU) identifier for the Product.

  - `productRatePlans.product.state` (string)
    Current state of the Product (for example, product_active).

  - `productRatePlans.product.customFields` (object)
    Custom field values defined for the Product.

  - `productRatePlans.productRatePlanCharges` (array)
    List of Product Rate Plan Charges (PRPCs) defined under this rate plan.
Each charge defines pricing, billing, taxation, and accounting details.

  - `productRatePlans.productRatePlanCharges.id` (string)
    Unique identifier of the Product Rate Plan Charge (PRPC).
    Example: "8a90876c8799b81801879cb516f8400b"

  - `productRatePlans.productRatePlanCharges.name` (string)
    Display name of the charge.
    Example: "New Component"

  - `productRatePlans.productRatePlanCharges.chargeType` (string)
    Type of charge (for example, recurring, usage, one_time).

  - `productRatePlans.productRatePlanCharges.chargeModel` (string)
    Pricing model applied to the charge (for example, flat_fee, tiered).

  - `productRatePlans.productRatePlanCharges.pricing` (object)
    Pricing configuration for the charge by currency.
Includes flat, unit, or tier-based amounts depending on the model.

  - `productRatePlans.productRatePlanCharges.pricing.flatAmounts` (object)
    Flat amount per billing period by currency.
    Example: {"USD":100}

  - `productRatePlans.productRatePlanCharges.pricing.minAmounts` (object)
    Minimum charge thresholds by currency.

  - `productRatePlans.productRatePlanCharges.pricing.maxAmounts` (object)
    Maximum charge thresholds by currency.

  - `productRatePlans.productRatePlanCharges.pricing.unitAmounts` (object)
    Per-unit charge amounts by currency.

  - `productRatePlans.productRatePlanCharges.pricing.tiers` (array)
    Tier-level pricing definitions for tiered or volume models.

  - `productRatePlans.productRatePlanCharges.billCycle` (object)
    Billing configuration for this charge.

  - `productRatePlans.productRatePlanCharges.billCycle.period` (string)
    Billing period, such as month or year.

  - `productRatePlans.productRatePlanCharges.billCycle.periodAlignment` (string)
    How the billing period aligns (for example, align_to_charge).

  - `productRatePlans.productRatePlanCharges.billCycle.timing` (string)
    Whether the charge bills in_advance or in_arrears.

  - `productRatePlans.productRatePlanCharges.taxMode` (string)
    Whether tax is included (tax_inclusive) or excluded (tax_exclusive).

  - `productRatePlans.productRatePlanCharges.taxable` (boolean)
    Indicates if the charge is taxable.

  - `productRatePlans.productRatePlanCharges.revenue` (object)
    Revenue recognition configuration for this charge.

  - `productRatePlans.productRatePlanCharges.revenue.revenueRecognitionRuleName` (string)
    Name of the revenue recognition rule (for example, “Recognize upon invoicing”).

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

  - `productRatePlans.productRatePlanCharges.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"

  - `productRatePlans.productRatePlanCharges.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.

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

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

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

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

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

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

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

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

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

  - `productRatePlans.productRatePlanCharges.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.

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

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

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

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

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

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

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

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

  - `productRatePlans.productRatePlanCharges.customFields` (object)
    Tenant-specific custom fields for the PRPC.

  - `productRatePlans.productRatePlanCharges.pricingSummary` (array)
    Human-readable price summary for quick display.
    Example: ["USD100"]

  - `productRatePlans.productRatePlanCharges.triggerEvent` (string)
    Event that triggers the charge (for example, contract_effective).

  - `productRatePlans.productRatePlanCharges.endDateCondition` (string)
    Condition that determines when the charge ends, for example subscription_end,
fixed_period, or specific_end_date.

  - `productRatePlans.productRatePlanCharges.upToPeriodsType` (string)
    Unit of time used when endDateCondition is duration-based (for example, billing_periods).

  - `productRatePlans.productRatePlanCharges.upToPeriods` (integer)
    Duration value used together with upToPeriodsType when endDateCondition is fixed_period.

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

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

  - `productRatePlans.productRatePlanCharges.updatedTime` (string)
    Timestamp when the charge was last updated.

  - `productRatePlans.productRatePlanCharges.createdTime` (string)
    Timestamp when the charge was created.

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.code` (string)
    Machine-readable error code identifying the failure type.

  - `errors.message` (string)
    Human-readable description of the error that provides more context about what went wrong.

  - `success` (boolean)

## 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.