Sign in
Commerce

Update a product rate plan charge with Dynamic Pricing

Update an existing product rate plan charge (PRPC). Use this API to update default pricing and/or conditional rate cards.

put/commerce/charges

Headers

Accept-Encodingstring

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-Encodingstring

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-Track-Idstring

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 (').

Zuora-Entity-Idsstring

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-Idsstring

Comma separated IDs. If you have <a href="https://docs.zuora.com/en/zuora-platform/organization-and-entity-management/multi-org/overview-of-multi-org" target="_blank">Zuora Multi-Org</a> 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.

Request body

Example request

{
  "charge": {
    "id": "9c4867ed55db43a89731605d5654d4ed",
    "pricing": {
      "flat_amounts": {
        "USD": 100
      }
    },
    "rate_cards": [
      {
        "attributes": [
          {
            "name": "Age",
            "operator": "<="
          }
        ],
        "pricing": {
          "flat_amounts": {
            "USD": 100
          }
        }
      }
    ],
    "accounting": {
      "accounting_code": "PRPC-REV-001",
      "accounts_receivable_account": "Accounts Receivable",
      "adjustment_liability_account": "adjustL-1",
      "adjustment_revenue_account": "adjustRev-1",
      "contract_asset_account": "CA-2",
      "contract_liability_account": "CL-2",
      "contract_recognized_revenue_account": "Contract Recognized Revenue",
      "deferred_revenue_account": "Deferred Revenue",
      "recognized_revenue_account": "ContractRevRec-1",
      "unbilled_receivables_account": "unbilledR-1"
    }
  }
}

Response

OK

attributesobject[]

Attribute metadata associated with Dynamic Pricing for this charge.

chargeFunction'charge_function_standard' | 'charge_function_prepayment' | 'charge_function_commitment_true_up' | 'charge_function_drawdown' | 'charge_function_credit_commitment' | 'charge_function_drawdown_and_credit_commitment'

Internal function/category of the charge used by rating.

chargeModelstring

Pricing model that determines how the amount is calculated.

chargeTypestring

Whether the charge recurs, rates usage, or is a one-time fee.

createdByIdstring

User ID that created the charge record.

createdTimestring date-time

Timestamp when the charge record was created.

customFieldsobject

Tenant-specific custom field values on the charge.

endDateConditionstring

Rule for when the charge ends.

upToPeriodsTypestring

Unit used for the fixed period when endDateCondition is fixed_period, for example, billing periods or days.

upToPeriodsinteger

Number of periods, in units of upToPeriodsType, that the charge remains active when endDateCondition is fixed_period.

extendedPriceobject

Calculated extended price details (model-dependent).

idstring

Unique identifier of the product rate plan charge (PRPC).

isChargeLevelMinCommitboolean

Whether a minimum commit is enforced at the charge level.

isCommittedboolean

Indicates if the charge definition is committed/finalized.

labelsobject

Free-form labels/tags attached to the charge.

listPriceBasestring

List price basis, for example, Per Billing Period, Per Month, Per Year.

specificListPriceBaseinteger

The number of months for the list price base of the charge. This field is required when the ListPriceBase field is set to Per Specific Months. The value must be a positive integer between 1 and 120, inclusive.

Notes:

  • This field is available only if you have the Annual List Price feature enabled.
  • To use this field, you must set the X-Zuora-WSDL-Version request header to 129 or later.
  • The value of this field is null if you do not set the value of the ListPriceBase field to Per Specific Months.
mergedRateCardsobject[]

Effective rate-card rows after merges (if any).

namestring

Display name of the charge in the plan.

negotiatedRateCardsobject[]

Customer- or deal-specific rate-card rows applied by negotiation.

netsuiteobject

NetSuite integration attributes mapped for this charge.

ocmJsonByCurrencyobject

Offer/OCM metadata keyed by currency (internal use).

organizationLabelsstring[]

Organization-level labels associated with the charge.

prepaidboolean

Indicates whether the charge is prepaid.

prepaymentUnitType'unit' | 'currency'

Unit type used for the prepayment charge.

priceChangeOptionstring

How price changes are applied across renewals/amendments.

pricingSummarystring[]

Human-readable price summary strings, for example, USD100.

pricingWaterfallsobject

Detailed pricing/waterfall breakdown (if available).

productChargeDefinitionsobject[]

Underlying charge definitions referenced for pricing lookup.

productRatePlanChargeNumberstring

PRPC number.

productRatePlanIdstring

ID of the plan (PRP) that owns this charge.

prorationOptionstring

How proration is handled relative to tenant defaults.

rateCardsobject[]

Dynamic Pricing rate-card rows configured on the charge.

taxCodestring

Tax code applied to the charge (for example, a tax category code).

taxModestring

Tax mode for the charge.

taxableboolean

Whether the charge is taxable.

triggerEventstring

Event that triggers the charge.

unitOfMeasurestring

Unit of measure used for pricing (for example, Each, Seats).

updatedByIdstring

User ID that last updated the charge record.

updatedTimestring date-time

Timestamp when the charge record was last updated.

useTenantDefaultForPriceChangeboolean

Whether tenant defaults govern price change behavior.

Example response

{
  "accounting": {
    "accountsReceivableAccount": "Accounts Receivable",
    "accountsReceivableAccountType": "AccountsReceivable",
    "deferredRevenueAccount": "Accounts Receivable",
    "deferredRevenueAccountType": "AccountsReceivable",
    "recognizedRevenueAccount": "Accounts Receivable",
    "recognizedRevenueAccountType": "AccountsReceivable"
  },
  "attributes": [],
  "billCycle": {
    "dayOfMonth": 5,
    "period": "bill_cycle_period_month",
    "periodAlignment": "align_to_charge",
    "timing": "in_advance",
    "type": "specific_day_of_month"
  },
  "chargeModel": "flat_fee",
  "chargeType": "recurring",
  "createdById": "53c162482f054f3ca08e1ec82dccfec9",
  "createdTime": "2025-10-13T07:46:02.000+00:00",
  "customFields": {},
  "discountOptions": {
    "applyDetails": [],
    "applyTo": [],
    "applyToBillingPeriodPartially": false,
    "reflectDiscountInNetAmount": false,
    "rollover": false,
    "stackedDiscount": false
  },
  "endDateCondition": "subscription_end",
  "upToPeriodsType": "billing_periods",
  "upToPeriods": 0,
  "extendedPrice": {},
  "id": "ad95b694d2b8442b84dc8ad26561c7d7",
  "isChargeLevelMinCommit": false,
  "isCommitted": false,
  "labels": {},
  "listPriceBase": "Per_Billing_Period",
  "mergedRateCards": [],
  "name": "Flat PRPC 1",
  "negotiatedRateCards": [],
  "netsuite": {},
  "ocmJsonByCurrency": {},
  "organizationLabels": [],
  "overageOptions": {
    "includedUnits": 0,
    "unusedUnitsCreditRates": {}
  },
  "prepaid": true,
  "chargeFunction": "charge_function_prepayment",
  "prepaymentUnitType": "unit",
  "prepayment": {
    "creditOption": "time_based",
    "operationType": "prepaid_operation_type_topup",
    "quantity": 10,
    "rollover": true,
    "rolloverApply": "apply_first",
    "rolloverPeriodLength": 6,
    "rolloverPeriods": 1,
    "unitOfMeasure": "Each",
    "validityPeriod": "specific_months",
    "validityPeriodAlignment": "vp_alignment_term_end",
    "validityPeriodProrationOption": "vp_proration_option_prorate_units",
    "specificValidityPeriodLength": 6,
    "rolloverPeriodType": "rollover_period_type_month",
    "rolloverFundPriority": 2,
    "rolloverEndDateType": "rollover_end_date_type_charge_end_date",
    "fundSupportAccountHierarchy": true,
    "drawdownPriority": 5,
    "drawdownScope": "commitment_level_account"
  },
  "priceChangeOption": "no_change",
  "pricing": {
    "adjustments": {},
    "discountAmounts": {},
    "discountPercentages": {},
    "flatAmounts": {
      "USD": 100
    },
    "maxAmounts": {},
    "minAmounts": {},
    "percentages": {},
    "tiers": [],
    "unitAmounts": {}
  },
  "pricingSummary": [
    "USD100"
  ],
  "pricingWaterfalls": {},
  "productChargeDefinitions": [],
  "productRatePlanChargeNumber": "PRPC-00000279",
  "productRatePlanId": "ee2d1ce1036c4dd6ae9d6945565ff7a0",
  "prorationOption": "default_from_tenant_setting",
  "rateCards": [],
  "revenue": {
    "excludeItemBillingFromRevenueAccounting": false,
    "excludeItemBookingFromRevenueAccounting": false,
    "legacyReporting": false,
    "revenueRecognitionRuleName": "Recognize upon invoicing"
  },
  "taxCode": "TAX_EXEMPT",
  "taxMode": "non_taxable",
  "taxable": false,
  "triggerEvent": "contract_effective",
  "unitOfMeasure": "Each",
  "updatedById": "53c162482f054f3ca08e1ec82dccfec9",
  "updatedTime": "2025-10-13T07:46:02.000+00:00",
  "useTenantDefaultForPriceChange": true
}

Changes

Changed in 1 of the 4 revisions of this API.1238

  • 7f43d4a77e8a1238See the full diff
    • ●

      added the new apply_first enum value to the prepayment/rolloverApply response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new apply_last enum value to the prepayment/rolloverApply response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new charge_function_commitment_true_up enum value to the chargeFunction response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new charge_function_credit_commitment enum value to the chargeFunction response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new charge_function_drawdown enum value to the chargeFunction response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new charge_function_drawdown_and_credit_commitment enum value to the chargeFunction response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new charge_function_prepayment enum value to the chargeFunction response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new charge_function_standard enum value to the chargeFunction response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new consumption_based enum value to the prepayment/creditOption response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new credit_option_unspecified enum value to the prepayment/creditOption response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new full_credit_back enum value to the prepayment/creditOption response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new time_based enum value to the prepayment/creditOption response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new optional request property charge/chargeFunction

      new-optional-request-property

    • ○

      added the new optional request property charge/drawdown

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/creditOption

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/drawdownPriority

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/drawdownScope

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/fundSupportAccountHierarchy

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/operationType

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/quantity

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/rollover

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/rolloverApply

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/rolloverEndDateType

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/rolloverFundPriority

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/rolloverPeriodLength

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/rolloverPeriodType

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/rolloverPeriods

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/specificValidityPeriodLength

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/unitOfMeasure

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/validityPeriod

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/validityPeriodAlignment

      new-optional-request-property

    • ○

      added the new optional request property charge/prepayment/validityPeriodProrationOption

      new-optional-request-property

    • ○

      added the new optional request property charge/prepaymentUnitType

      new-optional-request-property

    • ○

      added the optional property drawdown/conversionRate to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property drawdown/unitOfMeasure to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/drawdownPriority to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/drawdownScope to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/fundSupportAccountHierarchy to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/operationType to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/quantity to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/rolloverEndDateType to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/rolloverFundPriority to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/rolloverPeriodType to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/specificValidityPeriodLength to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/unitOfMeasure to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/validityPeriod to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/validityPeriodAlignment to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepayment/validityPeriodProrationOption to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property prepaymentUnitType to the response with the 200 status

      response-optional-property-added

    • ○

      the creditOption response's property default value time_based was added for the status 200

      response-property-default-value-added