# Commerce The Commerce APIs provide access to product catalog, billable metrics, features, plans, charges, runtime entitlement grants, access decisions, audit events, and order management functionality in Zuora. These endpoints are used to create, update, and query billable metrics, features, product-feature links, plan entitlement definitions, product rate plans, charges, dynamic pricing details, runtime entitlement grants, entitlement access decisions, and entitlement audit events 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 billable metric - [POST /commerce/billable-metrics](https://developer.zuora.com/v1-api-reference/api/commerce/createbillablemetric.md): Creates a billable metric that numbered metered features can use to measure entitlement usage. Specify the event types to process, the aggregation method, optional filters, computed properties, and group keys that calculate the metric separately for a subscription, model, or another dimension. ## List billable metrics - [GET /commerce/billable-metrics](https://developer.zuora.com/v1-api-reference/api/commerce/getbillablemetrics.md): Lists billable metrics that numbered metered features can use to measure entitlement usage. ## Retrieve a billable metric - [GET /commerce/billable-metrics/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/getbillablemetric.md): Retrieves a billable metric by its unique identifier or metric number. ## Update a billable metric - [PUT /commerce/billable-metrics/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/updatebillablemetric.md): Updates an existing billable metric. Use this operation to change fields such as name, description, filters, computed_properties, and group_keys. Include metric_key in the request body to identify the metric. ## Delete a billable metric - [DELETE /commerce/billable-metrics/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/deletebillablemetric.md): Deletes a billable metric by its unique identifier. ## Create a feature - [POST /commerce/features](https://developer.zuora.com/v1-api-reference/api/commerce/createfeature.md): Creates a catalog feature. Supported feature types are boolean (bool), enum (enumType), numbered metered, and numbered unmetered. Numbered metered features must include metricId to reference a billable metric. Numbered unmetered features omit metricId. ## List features - [GET /commerce/features](https://developer.zuora.com/v1-api-reference/api/commerce/getfeatures.md): Lists catalog features, including boolean, enum, numbered metered, and numbered unmetered features. ## Update a feature - [PUT /commerce/features](https://developer.zuora.com/v1-api-reference/api/commerce/updatefeature.md): Updates an existing catalog feature. Use this operation to change fields such as name, description, values, and tags. Omit tags to preserve existing tags. Send clear_tags: true to remove all tags. ## Search features - [POST /commerce/features/search](https://developer.zuora.com/v1-api-reference/api/commerce/searchfeatures.md): Searches catalog features. Use filters to match fields such as feature_type or feature_tag, or send filter.feature_tag. Soft-deleted features are excluded from the results. ## Retrieve a feature - [GET /commerce/features/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/getfeature.md): Retrieves a catalog feature by its unique identifier. ## Delete a feature - [DELETE /commerce/features/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/deletefeature.md): Deletes a catalog feature by its unique identifier. ## 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. ## Create an entitlement definition - [POST /commerce/plans/{id}/entitlements](https://developer.zuora.com/v1-api-reference/api/commerce/createentitlementdefinition.md): Creates a catalog entitlement definition on a plan. The definition associates a product feature with the plan. Include featureNumber or feature_number. Numbered features can include quantity or limitValue. Enum features can include values. A catalog entitlement definition is not a runtime entitlement grant. Runtime grants are created by the Z-EMS grant API when a subscription is created or a manual grant is issued. ## Update an entitlement definition - [PUT /commerce/plans/entitlements](https://developer.zuora.com/v1-api-reference/api/commerce/updateentitlementdefinition.md): Updates a catalog entitlement definition. Use this operation to link the definition to a charge, set boolean values, or change enforcement settings. ## Retrieve an entitlement definition - [GET /commerce/plans/entitlements/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/getentitlementdefinition.md): Retrieves a catalog entitlement definition by its unique identifier or entitlement number. A catalog entitlement definition is not a runtime entitlement grant. Runtime grants are created by the Z-EMS grant API when a subscription is created or a manual grant is issued. ## 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. ## Add a feature to a product - [PUT /commerce/products/{id}/features/add](https://developer.zuora.com/v1-api-reference/api/commerce/addproductfeature.md): Links a catalog feature to a product. Include feature_number or featureNumber. After a feature is linked to a product, you can create an entitlement definition on a plan that belongs to that product. ## 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. Results are returned in descending order by updated_on. The default pageSize is 20, and the maximum pageSize is 40. To control pagination, specify pagination.page and pagination.pageSize in the request body. 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. ## List entitlement audit events - [GET /commerce/entitlements/audit-events](https://developer.zuora.com/v1-api-reference/api/commerce/getentitlementauditevents.md): Lists entitlement audit events. Filter results by account, feature, grant, subscription, event type, and date. ## Authorize entitlement consumption - [POST /commerce/entitlements/authorize](https://developer.zuora.com/v1-api-reference/api/commerce/authorizeentitlementconsumption.md): Authorizes consumption against a numbered metered feature and deducts requestedQuantity from the remaining entitlement balance when the request is allowed. ## Check entitlements by tag - [POST /commerce/entitlements/bulk-challenge](https://developer.zuora.com/v1-api-reference/api/commerce/validateentitlementsbytag.md): Checks whether an account has access to features that match featureTag, or to the features in featureKeys. Do not send featureTag and featureKey in the same request. ## Check multiple entitlements - [POST /commerce/entitlements/bulk-check](https://developer.zuora.com/v1-api-reference/api/commerce/validateentitlementfeatures.md): Checks whether an account has access to multiple features in one request. Include requestedQuantity when evaluating numbered metered features. ## Create entitlement grants in bulk - [POST /commerce/entitlements/bulk-grant](https://developer.zuora.com/v1-api-reference/api/commerce/bulkgrantentitlements.md): Creates runtime entitlement grants for multiple accounts or subscriptions in a single call. Each item uses the same shape as POST /commerce/entitlements/grant, but this operation reports each item's outcome independently instead of failing the whole batch on the first bad item. Use skipExisting to make batch re-submission idempotent, and continueOnError to keep processing remaining items after a failure. The request is rejected if grantEntitlementRequest is empty or contains more than 500 items. Processing is synchronous and not transactional across items. Each item's rows are written independently, so a partially applied item is safe to resubmit when skipExisting is true. ## Revoke entitlement grants - [POST /commerce/entitlements/bulk-revoke](https://developer.zuora.com/v1-api-reference/api/commerce/bulkrevokeentitlements.md): Revokes one or more runtime entitlement grants. Include revokedDate when the revocation should take effect on a specific date. ## Check entitlement access - [POST /commerce/entitlements/challenge](https://developer.zuora.com/v1-api-reference/api/commerce/validateentitlementaccess.md): Checks whether an account has access to a feature. For numbered metered features, include requestedQuantity. For enum features, include enumValues. ## Create entitlement grants - [POST /commerce/entitlements/grant](https://developer.zuora.com/v1-api-reference/api/commerce/createentitlementgrants.md): Creates one or more runtime entitlement grants. Use this operation to issue a manual grant for an account, independently of a catalog entitlement definition on a plan. ## List entitlement grants - [GET /commerce/entitlements/grants](https://developer.zuora.com/v1-api-reference/api/commerce/getentitlementgrants.md): Lists runtime entitlement grants. Filter results by account, subscription, feature, state, or charge source. ## Retrieve an entitlement grant - [GET /commerce/entitlements/grants/{entitlementKey}](https://developer.zuora.com/v1-api-reference/api/commerce/getentitlementgrant.md): Retrieves one runtime entitlement grant by its entitlement key. ## Update an entitlement grant - [POST /commerce/entitlements/{entitlementKey}/modify](https://developer.zuora.com/v1-api-reference/api/commerce/updateentitlementgrant.md): Updates the dates or quantity of a runtime entitlement grant. Use redate with startDate and/or endDate to change the grant term, or increment and decrement with delta to change the granted quantity. Billable grants may return status: queued with an orderIntentId. ## Update entitlement grant state - [POST /commerce/entitlements/{entitlementKey}/state](https://developer.zuora.com/v1-api-reference/api/commerce/updateentitlementgrantstate.md): Updates the state of a runtime entitlement grant. Supported action values are pause, resume, activate, deactivate, and revoke.