Managing Negotiable Price table for usage charges
Negotiated Price table
When a usage charge has enabled dynamic pricing and has some pricing attributes tied to fields in the usage record, the price will be determined when processing the usage records, not at the time of subscription. For such pricing attributes, map it to a field of the Usage object, subscribe to it via Orders API or UI and use Zuora Mediation to load the usage data.
When processing the records of such usage charges, Zuora Mediation retrieves the relevant pricing attribute values from each record and uses them to get the correct price dynamically.
In addition, you can also customize such usage charge’s standard price table with a negotiated price table by updating rate card entries when subscribing to the rate plans. The negotiated price table is created via the negotiatedPriceTable tag in the following order actions through REST API:
- addProduct
- createSubscription
- changePlan
After the negotiated price table is created, you can also update it via updateProduct order action through REST API.
-
Zuora only allows the user to create a Negotiated Price Table for such Usage charge that has defined pricing attributes mapped to Usage object fields.
-
The data in the negotiatedPriceTable tag within the Order API payload override the existing rate card entries in the standard price table. During pricing evaluation the unchanged rate card entries in the standard price table are still effective.
-
For the reserved pricing attribute, CustomerReference, its value is set by Zuora automatically when creating the negotiated price table. Please do not include it in the negotiatedPriceTable tag and pricingAttributes tag in the payload.
-
The effectiveDate in the rate cards indicates when the new list price will be effective. We recommend the user to include effectiveDate in the payload. When effectiveDate doesn’t present, the order action’s effective date will be used.
Pre-configuration
Create the usage charge with the following pricing attributes:
| Pricing Attribute Name | Description | Category | Mapping Relationship / Data Type |
|---|---|---|---|
| AccountType | The account type. | Mapped |
{ "field": "Type__c", "object": "account" } |
| UsageState | The state associated with the usage record. | Mapped |
{ "field": "state__c", "object": "usage" } |
| SubscriptionRatePlanChannel | The sales channel of the rate plan. | Mapped |
{ "field": "Channel__c", "object": "rateplan" } |
| Age | The end user’s age. | External | Integer |
| CustomerReference | Reserved attribute to enable negotiated price table. | Reserved . | String |
| EffectiveDate |
The effective date of the price. |
Default | Datetime |
Configure the usage charge’s standard price table as follows:
Create Negotiated Price table
To subscribe to a rate plan and define a negotiated price table for the usage charge by creating an order:
| Request | POST /v1/orders/ |
|---|---|
| Request Body |
{
"orderDate": "$Today",
"existingAccountNumber": "$AccountNum",
"subscriptions": [
{
"orderActions": [
{
"type": "CreateSubscription",
"triggerDates": [
{
"name": "ContractEffective",
"triggerDate": "$Today"
},
{ "name": "ServiceActivation",
"triggerDate": "$Today"
},
{
"name": "CustomerAcceptance",
"triggerDate": "$Today"
}
],
"createSubscription":
{
"subscriptionOwnerAccountNumber": "$AccountNum",
"terms":
{
"initialTerm":
{
"startDate":"$Today",
"period": 12,
"periodType": "Month",
"termType": "TERMED"
},
"renewalTerms": [
{
"period": 12,
"periodType": "Month"
}
],
"renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
"autoRenew": true
},
"subscribeToRatePlans": [
{
"productRatePlanId":"$productRatePlanId",
"customFields": {
"RateClass__c": "Low"
},
"chargeOverrides": [{
"productRatePlanChargeId":"$productRatePlanChargeId",
"pricingAttributes": {
"Age": 33
},
"negotiatedPriceTable": [
{
"attributes": [
{
"name": "AccountType",
"operator": "==",
"value": "VIP"
},
{
"name": "UsageState",
"operator": "==",
"value": "CA"
},
{
"name": "SubscriptionRatePlanChannel",
"operator": "==",
"value": "Reseller"
},
{
"name": "Age",
"operator": ">",
"value": 18
},
{
"name": "EffectiveDate",
"operator": ">=",
"value": "2025-05-12T09:24:25Z[UTC]"
}
],
"pricing":
{
"tiers": [
{
"from": 0,
"up_to": 10,
"price_format": "price_format_per_unit",
"unit_amounts":
{
"USD": 210
}
},
{
"from": 11,
"up_to": 20,
"price_format": "price_format_per_unit",
"unit_amounts":
{
"USD": 200
}
},
{
"from": 21,
"price_format": "price_format_per_unit",
"unit_amounts":
{
"USD": 190
}
}
]
}
}
]
}
]
}
]
}
}
]
}
]
}
|
-
Determine the values of the following variables and configure the dynamic pricing enabled charge in the product catalog accordingly:
Variable Description $AccountNum The number of the account that will own the order and the subscription. For example, A00000001. $produictRatePlanId The ID of the subscription rate plan. For example, edcaaadd4f198397d0583bc94b90000e. $productRatePlanChargeId The ID of the product rate plan charge to use when adding the product rate plan. For example, 8ceac04750d648f493363556d139d061. $Today Today's date. For example, 2025-06-16. -
Refer to the example payload to create a new order.
This example will create a new subscription to subscribe to the usage charge $productRatePlanChargeId and override the tiered price of one rate card entry.
In the chargeOverrides section, the user:
- provides the value of external attribute Age via pricingAttributes tag.
- overrides the tiered price of the last rate card entry (see the screenshot below) via the negotiatedPriceTable tag by increasing each tier’s price by 100.
-
After the subscription is created, the subscribed usage charge’s negotiated price table has the following rate cards:
Update Negotiated Price table
To update the negotiated price table of a usage charge by creating an order:
- Determine the values of the following variables and configure the dynamic pricing enabled charge in the product catalog accordingly:
Variable Description $AccountNum The number of the account that will own the order and the subscription. For example, A00000001. $SubscriptionNumber The number of the subscription that owns the rate plans. For example, A-S0000001. $subscriptionRatePlanId The ID of the subscription rate plan. For example, 8a90876c84ae5ef70184c2080c307343.. $chargeNumber The number of the subscription rate plan charge to be updated. For example, C-00036197. $Today Today's date. For example, 2025-07-20. $EffectiveDate The date from which the subscription will be effective. For example, 2025-05-12T09:24:25Z[UTC]. -
Refer to the example payload to create a new order. In the chargeUpdates section, the user changes the tiered price of the last rate card entry via the negotiatedPriceTable tag by increasing each tier’s price by 100 again.
In the chargeUpdates section, the user changes the tiered price of the last rate card entry via the negotiatedPriceTable tag by increasing each tier’s price by 100 again.
The usage charge with number $chargeNumber was added by the create subscription order in the previous section.
Request POST /v1/orders/Request Body { "existingAccountNumber": "$AccountNum", "orderDate": "$Today", "subscriptions": [ { "subscriptionNumber": "$subscriptionNumber", "orderActions": [ { "updateProduct": { "ratePlanId": "$subscriptionRatePlanId", "chargeUpdates": [ { "chargeNumber": "$chargeNumber", "negotiatedPriceTable": [ { "attributes": [ { "name": "AccountType", "operator": "==", "value": "VIP" }, { "name": "UsageState", "operator": "==", "value": "CA" }, { "name": "SubscriptionRatePlanChannel", "operator": "==", "value": "Reseller" }, { "name": "Age", "operator": ">", "value": 18 }, { "name": "EffectiveDate", "operator": ">=", "value": "2025-05-12T09:24:25Z[UTC]" } ], "pricing": { "tiers": [ { "from": 0, "up_to": 10, "price_format": "price_format_per_unit", "unit_amounts": { "USD": 310 } }, { "from": 11, "up_to": 20, "price_format": "price_format_per_unit", "unit_amounts": { "USD": 300 } }, { "from": 21, "price_format": "price_format_per_unit", "unit_amounts": { "USD": 290 } } ] } } ] } ] }, "triggerDates": [ { "name": "ContractEffective", "triggerDate": "$Today" }, { "name": "CustomerAcceptance", "triggerDate": "$Today" }, { "name": "ServiceActivation", "triggerDate": "$Today" } ], "type": "UpdateProduct" } ] } ] } -
After the update is completed, the subscribed usage charge’s negotiated price table has the following rate cards:
