# Commerce

The Commerce APIs provide access to product catalog, plans, charges, and order
management functionality in Zuora. These endpoints are used to create, update,
and query product rate plans, charges, and dynamic pricing details that drive
subscription and billing behavior.

In a typical use case, the Commerce APIs are called to provision new products
or plans in the catalog, configure dimensional pricing, or submit orders that
create and modify subscriptions.

Changes made with these APIs affect the product catalog and active subscriptions,
depending on the endpoint. Catalog changes update future subscription behavior,
while order operations directly impact customer subscriptions in real time.'


## Create a product rate plan charge with Dynamic Pricing

 - [POST /commerce/charges](https://developer.zuora.com/v1-api-reference/api/commerce/createproductrateplanchargewithdynamicpricing.md): Create a product rate plan charge (PRPC) in the Product Catalog.
Use this endpoint to configure Dynamic Pricing, including default pricing at the charge level 
and conditional rate cards evaluated by attribute values.

## Update a product rate plan charge with Dynamic Pricing

 - [PUT /commerce/charges](https://developer.zuora.com/v1-api-reference/api/commerce/updateproductrateplanchargewithdynamicpricing.md): Update an existing product rate plan charge (PRPC). Use this API to update default pricing and/or conditional rate cards.

## Query a product rate plan charge with Dynamic Pricing

 - [POST /commerce/charges/query](https://developer.zuora.com/v1-api-reference/api/commerce/queryproductrateplanchargewithdynamicpricing.md): 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.

## Create a product with plans and charges

 - [POST /commerce/products](https://developer.zuora.com/v1-api-reference/api/commerce/createproduct.md): Create a product in the Product Catalog with one or more plans and charges.
Charges can be usage (per-unit), recurring (flat fee), or other supported models.

## Update a product

 - [PUT /commerce/products](https://developer.zuora.com/v1-api-reference/api/commerce/updateproduct.md): Updates an existing product in the Product Catalog. Use this API to update core product fields
such as name, description, category, effective dates, and custom fields.

## Create a product rate plan

 - [POST /commerce/plans](https://developer.zuora.com/v1-api-reference/api/commerce/createplan.md): Create a product rate plan (Plan) under an existing product.
A plan includes one or more charges. Each charge must include:
  - name
  - charge_model
  - charge_type
  - bill_cycle
  - trigger_event
  - end_date_condition
  - pricing

  Optional charge fields include: unit_of_measure, list_price_base, and accounting (with accounting_code, deferred_revenue_account, recognized_revenue_account).

## Update a product rate plan

 - [PUT /commerce/plans](https://developer.zuora.com/v1-api-reference/api/commerce/updateproductrateplan.md): Updates an existing Product Rate Plan (PRP) in the Product Catalog. 
Use this API to update core plan fields such as name, description, grade, and effective dates.

## Query product rate plan details

 - [POST /commerce/plans/query](https://developer.zuora.com/v1-api-reference/api/commerce/querycommerceproductrateplans.md): Retrieve details of a single product rate plan (PRP) from the Product Catalog. You can expand associated product rate plan charges for each plan.
This operation is a strict lookup and requires product_rate_plan_key. It does not support attributes or other list-style filters.
To browse or filter plans (including by attributes), use  the "Query product rate plans" operation (POST /commerce/plans/list).

## Query product rate plans

 - [POST /commerce/plans/list](https://developer.zuora.com/v1-api-reference/api/commerce/querycommerceplanslist.md): 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.

## Retrieve a product by key

 - [POST /commerce/products/{product_key}](https://developer.zuora.com/v1-api-reference/api/commerce/getproductbykey.md): Retrieves detailed information about a specific product by its unique product number or ID. 
You can optionally specify related objects to expand in the request body.

## Query legacy products from the Product Catalog

 - [POST /commerce/legacy/products/list](https://developer.zuora.com/v1-api-reference/api/commerce/querylegacyproducts.md): 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.

## Update a product rate plan charge tier

 - [PUT /commerce/tiers](https://developer.zuora.com/v1-api-reference/api/commerce/updatetier.md): Updates the price and other editable attributes, when supported, for a specific Product Rate Plan Charge Tier.

## Query purchase options by PRP ID

 - [POST /commerce/purchase-options/list](https://developer.zuora.com/v1-api-reference/api/commerce/querypurchaseoptionsbyprpid.md): 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.