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

 - [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 g
 - [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.
 - [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.
 - [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
 - [DELETE /commerce/billable-metrics/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/deletebillablemetric.md): Deletes a billable metric by its unique identifier.
 - [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 b
 - [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.
 - [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 a
 - [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.
 - [GET /commerce/features/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/getfeature.md): Retrieves a catalog feature by its unique identifier.
 - [DELETE /commerce/features/{id}](https://developer.zuora.com/v1-api-reference/api/commerce/deletefeature.md): Deletes a catalog feature by its unique identifier.
 - [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
 - [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.
 - [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 c
 - [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.
 - [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.
 - [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_
 - [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.
 - [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 **requir
 - [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.
 - [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
 - [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.
 - [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
 - [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.
 - [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 produ
 - [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 custome
 - [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**.
 - [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
 - [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.
 - [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.
 - [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.
 - [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.
 - [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
 - [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.
 - [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`.
 - [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.
 - [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.
 - [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.
 - [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
 - [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`.