# Query legacy products from the Product Catalog

This operation is functionally equivalent to the "Query products from the Product Catalog" operation, except that it returns results
in the V1 response format. It is primarily intended for customers migrating from older V1 integrations 
who want to use new Commerce capabilities — such as Dynamic Pricing—without refactoring their existing integrations.


Unlike the "Query products from the Product Catalog" operation, this operation does not retrieve a different set of products.  
It returns the same product catalog data as the newer operation, but formatted in a flattened V1-style response structure that:
  - Uses flattened fields instead of grouped objects such as discount_options, revenue, or bill_cycle.
  - Retains V1 field names for easier migration from existing V1 operations, for example:
    - Retrieve a product rate plan charge.
    - Retrieve a product rate plan.
    - Retrieve a product.
  - Keeps certain objects, such as netsuite and customFields, as grouped structures instead of flattening them.

  Recommended Usage 
  - Use this operation if you are migrating from V1 APIs and need to maintain compatibility with existing integrations.
  - For new integrations, use the "Query products from the Product Catalog" operation instead, as it returns structured responses optimized for the Commerce feature.

Endpoint: POST /commerce/legacy/products/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-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 (').

## Request fields (application/json):

  - `filters` (array)
    Filter conditions for querying legacy products. 
Each filter defines a field, an operator, and a value to match against.
Common filter fields include id, name, product_number, or category.
    Example: [{"field":"id","operator":"EQ","value":"8a90850b963680cb01963ad92a7a46e0"}]

  - `filters.field` (string, required)
    Field name to filter by.
    Enum: "id", "name", "product_number", "category"

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

  - `filters.value` (string, required)
    Value to match for the specified field.
The data type depends on the field being filtered.
    Example: "8a90850b963680cb01963ad92a7a46e0"

  - `expand` (object)
    Defines whether to include related entities such as Product Rate Plans (PRPs) and 
Product Rate Plan Charges (PRPCs) in the response. Each key corresponds to an entity type that can be expanded.
    Example: {"product_rate_plans":true,"product_rate_plan_charges":true}

  - `expand.product_rate_plans` (boolean)
    When true, includes Product Rate Plans (PRPs) under each product.
    Example: true

  - `expand.product_rate_plan_charges` (boolean)
    When true, includes Product Rate Plan Charges (PRPCs) for each rate plan.
    Example: true

## Response 200 fields (application/json):

  - `values` (array)
    List of legacy products matching the query.

  - `values.id` (string)
    Unique identifier of the product.
    Example: "1a951a549f464e93bea1bfe7b8ffce1f"

  - `values.name` (string)
    Product name.
    Example: "ABP demo product"

  - `values.description` (string)
    Product description.

  - `values.category` (string)
    Product category label.
    Example: "Add On Services"

  - `values.productNumber` (string)
    Product number in the catalog.
    Example: "PC-00011567"

  - `values.sku` (string)
    Product SKU.
    Example: "SKU-00011727"

  - `values.effectiveStartDate` (string)
    Date when the product becomes effective in the catalog.
    Example: "2025-05-01"

  - `values.effectiveEndDate` (string)
    Date when the product is no longer effective in the catalog.
    Example: "2025-05-31"

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

  - `values.allowFeatureChanges` (boolean)
    Whether features on this product can be changed.

  - `values.contextFilters` (array)
    Context filters applied to the product.

  - `values.features` (array)
    Product features.

  - `values.legacyFeatures` (array)
    Legacy features associated with this product.

  - `values.customFields` (object)
    Custom fields on the product.
    Example: {"DecimalNumber__c":1.12,"test5bool__c":true}

  - `values.customObjects` (object,null)
    Custom objects linked to this product.

  - `values.netsuite` (object)
    Netsuite integration attributes.

  - `values.organizationLabels` (array)
    Organization labels for the product.

  - `values.createdBy` (string)
    ID of the user who created the product.
    Example: "34aa321aa7cd46d19bebcf9c090af7a0"

  - `values.createdTime` (string)
    Timestamp when the product was created.
    Example: "2025-05-01T19:32:51.000+00:00"

  - `values.updatedBy` (string)
    ID of the user who last updated the product.
    Example: "34aa321aa7cd46d19bebcf9c090af7a0"

  - `values.updatedTime` (string)
    Timestamp when the product was last updated.
    Example: "2025-05-12T08:19:44.000+00:00"

  - `values.productRatePlans` (array)
    Product rate plans (PRPs) of the product.

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

  - `values.productRatePlans.name` (string)
    Rate plan name.
    Example: "Demo Rate Plan"

  - `values.productRatePlans.description` (string)
    Rate plan description.

  - `values.productRatePlans.displayName` (string)
    Rate plan display name.

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

  - `values.productRatePlans.effectiveStartDate` (string)
    Effective start date of the rate plan.
    Example: "2025-05-01"

  - `values.productRatePlans.effectiveEndDate` (string)
    Effective end date of the rate plan.
    Example: "2025-05-31"

  - `values.productRatePlans.activeCurrencies` (array)
    Currencies with active pricing.
    Example: ["USD"]

  - `values.productRatePlans.productId` (string)
    Owning product ID.
    Example: "1a951a549f464e93bea1bfe7b8ffce1f"

  - `values.productRatePlans.productRatePlanNumber` (string)
    Rate plan number.
    Example: "PRP-00012518"

  - `values.productRatePlans.attributes` (array)
    Attribute definitions associated with the plan.

  - `values.productRatePlans.contextFilters` (array)
    Context filters at the plan level.

  - `values.productRatePlans.customFields` (object)
    Custom fields at the plan level.

  - `values.productRatePlans.entitlements` (array)
    Entitlements linked to the plan.

  - `values.productRatePlans.externalIdSourceSystem` (string)
    External ID source system.

  - `values.productRatePlans.externalManagedPlanIds` (array)
    External plan identifiers.

  - `values.productRatePlans.organizationLabels` (array)
    Organization labels.

  - `values.productRatePlans.createTime` (string)
    Plan creation time.
    Example: "2025-05-01T19:33:11.000+00:00"

  - `values.productRatePlans.createdBy` (string)
    ID of the user who created the plan.

  - `values.productRatePlans.updateTime` (string)
    Plan update time.

  - `values.productRatePlans.updatedBy` (string)
    ID of the user who updated the plan.

  - `values.productRatePlans.productRatePlanCharges` (array)
    Charges (PRPCs) that belong to this product rate plan.

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

  - `values.productRatePlans.productRatePlanCharges.name` (string)
    Charge name.
    Example: "Charge with state 2"

  - `values.productRatePlans.productRatePlanCharges.model` (string)
    Charge model.
    Example: "PerUnit"

  - `values.productRatePlans.productRatePlanCharges.uom` (string)
    Unit of measure.
    Example: "Each"

  - `values.productRatePlans.productRatePlanCharges.billingDay` (string)
    Billing day behavior.

  - `values.productRatePlans.productRatePlanCharges.billingPeriod` (string)
    Billing period (e.g., Month).
    Example: "Month"

  - `values.productRatePlans.productRatePlanCharges.billingPeriodAlignment` (string)
    Alignment for billing period.
    Example: "AlignToCharge"

  - `values.productRatePlans.productRatePlanCharges.billingTiming` (string)
    Billing timing (IN_ADVANCE or IN_ARREARS).
    Example: "IN_ADVANCE"

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

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

  - `values.productRatePlans.productRatePlanCharges.includedUnits` (number)
    Included units for usage or dimensional pricing.

  - `values.productRatePlans.productRatePlanCharges.isDimensionalPrice` (boolean)
    Indicates if the charge uses dimensional pricing.
    Example: true

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

  - `values.productRatePlans.productRatePlanCharges.productRatePlanId` (string)
    Owning PRP ID.
    Example: "c3a52dd029704b7e89274c9e7e8fd99c"

  - `values.productRatePlans.productRatePlanCharges.productRatePlanChargeNumber` (string)
    Charge number.
    Example: "PRPC-00017066"

  - `values.productRatePlans.productRatePlanCharges.attributes` (array)
    Dynamic pricing attributes bound to the charge.

  - `values.productRatePlans.productRatePlanCharges.attributes.name` (string)
    Attribute name
    Example: "State"

  - `values.productRatePlans.productRatePlanCharges.attributes.type` (string)
    Attribute type
    Example: "String"

  - `values.productRatePlans.productRatePlanCharges.attributes.mapping` (object)
    Source mapping for attribute values.

  - `values.productRatePlans.productRatePlanCharges.attributes.mapping.object` (string)
    Source object
    Example: "account"

  - `values.productRatePlans.productRatePlanCharges.attributes.mapping.field` (string)
    Source field
    Example: "state__c"

  - `values.productRatePlans.productRatePlanCharges.pricing` (array)
    Currency pricing entries.

  - `values.productRatePlans.productRatePlanCharges.pricing.currency` (string)
    ISO currency code
    Example: "USD"

  - `values.productRatePlans.productRatePlanCharges.pricing.price` (number)
    Price for the currency
    Example: 101

  - `values.productRatePlans.productRatePlanCharges.pricing.tiers` (array)
    Tier definitions (if applicable).

  - `values.productRatePlans.productRatePlanCharges.pricingSummary` (array)
    Human-readable pricing summary.
    Example: ["USD101/Each"]

  - `values.productRatePlans.productRatePlanCharges.pricingWaterfalls` (object)
    Price sources such as base and segment prices.

  - `values.productRatePlans.productRatePlanCharges.revenue` (object)
    Revenue recognition settings.

  - `values.productRatePlans.productRatePlanCharges.netsuite` (object)
    Netsuite integration settings.

  - `values.productRatePlans.productRatePlanCharges.customFields` (object)
    Custom fields on the charge.

  - `values.productRatePlans.productRatePlanCharges.accounting` (object)
    Accounting configuration.

  - `values.productRatePlans.productRatePlanCharges.applyToBillingPeriodPartially` (boolean)
    Indicates whether the charge is applied to partial billing periods.

  - `values.productRatePlans.productRatePlanCharges.creditOption` (string)
    Specifies how credits are handled for this charge, for example, credit_option.

  - `values.productRatePlans.productRatePlanCharges.deliverySchedule` (object)
    Defines the delivery frequency and applicable days for the charge.

  - `values.productRatePlans.productRatePlanCharges.discountRollover` (boolean)
    Indicates whether unused discounts roll over to the next billing period.

  - `values.productRatePlans.productRatePlanCharges.endDateCondition` (string)
    Defines when the charge ends, such as at the subscription end or after a fixed term.

  - `values.productRatePlans.productRatePlanCharges.extendedPrice` (object)
    Contains calculated extended pricing details for the charge, if applicable.

  - `values.productRatePlans.productRatePlanCharges.isCommitted` (boolean)
    Indicates whether this charge is part of a committed contract.

  - `values.productRatePlans.productRatePlanCharges.isPrepaid` (boolean)
    Specifies whether the charge is prepaid.

  - `values.productRatePlans.productRatePlanCharges.isRollover` (boolean)
    Indicates whether unused units or balances roll over to subsequent periods.

  - `values.productRatePlans.productRatePlanCharges.isStackedDiscount` (boolean)
    Indicates whether this charge supports multiple stacked discounts.

  - `values.productRatePlans.productRatePlanCharges.labels` (object)
    Stores additional key-value metadata labels associated with the charge.

  - `values.productRatePlans.productRatePlanCharges.ocmJsonByCurrency` (object)
    Contains pricing or configuration metadata per currency in JSON format.

  - `values.productRatePlans.productRatePlanCharges.priceChangeOption` (string)
    Defines how price changes are handled when the product or rate plan changes.

  - `values.productRatePlans.productRatePlanCharges.productChargeDefinitions` (array)
    List of charge-level definition objects that specify pricing and behavior for the charge.

  - `values.productRatePlans.productRatePlanCharges.productDiscountApplyDetails` (array)
    Details of how discounts are applied to this charge.

  - `values.productRatePlans.productRatePlanCharges.rateCards` (array)
    Associated rate card definitions used for dynamic or segmented pricing.

  - `values.productRatePlans.productRatePlanCharges.reflectDiscountInNetAmount` (boolean)
    Indicates whether discounts are reflected directly in the net amount of the charge.

  - `values.productRatePlans.productRatePlanCharges.rolloverApply` (string)
    Defines how rolled-over balances or discounts are applied.

  - `values.productRatePlans.productRatePlanCharges.rolloverPeriodLength` (number)
    Length of each rollover period, in the unit specified by the product configuration.

  - `values.productRatePlans.productRatePlanCharges.rolloverPeriods` (number)
    Total number of rollover periods allowed for this charge.

  - `values.productRatePlans.productRatePlanCharges.taxCode` (string)
    Tax code applied to the charge for taxation purposes.

  - `values.productRatePlans.productRatePlanCharges.taxMode` (string)
    Tax mode for this charge, for example, NonTaxable or Taxable.

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

  - `values.productRatePlans.productRatePlanCharges.type` (string)
    The charge type, for example, Recurring, OneTime, or Usage.

  - `values.productRatePlans.productRatePlanCharges.updatedById` (string)
    ID of the user who last updated the charge.

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

  - `values.productRatePlans.productRatePlanCharges.createdById` (string)
    ID of the user who created the charge.

  - `values.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.