# CRUD: Retrieve a rate plan charge

Endpoint: GET /v1/object/rate-plan-charge/{id}
Version: 2025-12-17

## Header parameters:

  - `Accept-Encoding` (string)
    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-Encoding` (string)
    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.

  - `Authorization` (string)
    The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

  - `Zuora-Entity-Ids` (string)
    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 do not need to set this header.

  - `Zuora-Track-Id` (string)
    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 (').

## Query parameters:

  - `fields` (string)
    Object fields to return

## Path parameters:

  - `id` (string, required)
    Object id

## Response 200 fields (application/json):

  - `AccountingCode` (string)
    The accounting code for the charge. Accounting codes group transactions that contain similar accounting attributes.

Character limit: 100

Values: inherited from ProductRatePlanCharge.AccountingCode

Note: This value changes if ProductRatePlanCharge.AccountingCode is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.AccountingCode is updated.

  - `ApplyDiscountTo` (string)
    Specifies the type of charges a specific discount applies to. Character limit: 21 Values: inherited from ProductRatePlanCharge.ApplyDiscountTo

  - `BillCycleDay` (integer)
    Indicates the charge's billing cycle day (BCD), which is when bill runs generate invoices for charges associated with the product rate plan charge or the account.
Character limit: 2 Values: inherited from ProductRatePlanCharge.BillCycleDay

  - `BillCycleType` (string)
    Specifies how to determine the billing day for the charge.
Character limit: 20 Values: inherited from ProductRatePlanCharge.BillCycleType Note: You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.

  - `BillingPeriod` (string)
    Allows billing period to be overridden on rate plan charge.
Values: inherited from ProductRatePlanCharge.BillingPeriod Note: You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.

  - `BillingPeriodAlignment` (string)
    Aligns charges within the same subscription if multiple charges begin on different dates.
Character limit: 24 Values: inherited from ProductRatePlanCharge.BillingPeriodAlignment

  - `BillingTiming` (string)
    The billing timing for the charge. You can choose to bill in advance or in arrears for recurring charge types. This field is not used in one-time or usage based charge types.
Character limit: Values: one of the following:

- In Advance
- In Arrears
Note: You can override the value inherited from the Product Rate Plan Charge when a subscription has a recurring charge type.

  - `ChargeModel` (string)
    Determines how to evaluate charges. Charge models must be individually activated in the web-based UI.
Character limit: 29 Values: inherited from ProductRatePlanCharge.ChargeModel

  - `ChargeNumber` (string)
    A unique number that identifies the charge. This number is returned as a string.
Character limit: 50 Values: one of the following:

- automatically generated if left null
- a unique number of 50 characters or fewer

  - `ChargeType` (string)
    Specifies the type of charge.
Character limit: 9 Values: inherited from ProductRatePlanCharge.ChargeType

  - `ChargedThroughDate` (string)
    The date through which a customer has been billed for the charge.
Character limit: 29 Values: automatically generated

  - `CreatedById` (string)
    The ID of the Zuora user who created the RatePlanCharge object. Character limit: 32 Values: automatically generated

  - `CreatedDate` (string)
    The date when the RatePlanCharge object was created.
Character limit: 29 Values: automatically generated

  - `DMRC` (number)
    A delta monthly recurring charge is the change in monthly recurring revenue caused by an amendment or a new subscription. Character limit: 16 Values: automatically generated

  - `DTCV` (number)
    After an Amendment, the change in the total contract value (TCV) amount for this charge, compared with its previous value.
Character limit: 16 Values: automatically generated

  - `Description` (string)
    A description of the charge.
Character limit: 500 Values: inherited from ProductRatePlanCharge.Description

  - `DiscountLevel` (string)
    Specifies if the discount applies to just the product rate plan, the entire subscription, or to any activity in the account. Character limit: 12 Values: inherited from ProductRatePlanCharge.DiscountLevel

  - `EffectiveEndDate` (string)
    The date when the segmented charge ends or ended.
Character limit: 16 Values: automatically generated

  - `EffectiveStartDate` (string)
    The date when the segmented charge starts or started.
Character limit: 16 Values: automatically generated

  - `EndDateCondition` (string)
    Defines when the charge ends after the charge trigger date. This field can be updated when Status is Draft.
Values: one of the following:

- SubscriptionEnd: The charge ends on the subscription end date after the charge trigger date. This is the default value.
- FixedPeriod: The charge ends after a specified period based on the trigger date of the charge. If you set this field to FixedPeriod, you must specify the length of the period and a period type by defining the UpToPeriods and UpToPeriodsType fields.
- SpecificEndDate: The specific date on which the charge ends. If you set this field to SpecificEndDate, you must specify the specific date by defining the SpecificEndDate field.

Note: If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.

  - `ExcludeItemBillingFromRevenueAccounting` (boolean)
    The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.

Note: To use this field, you must set the X-Zuora-WSDL-Version request header to 115 or later. Otherwise, an error occurs.

Note: This field is only available if you have the Billing - Revenue Integration feature enabled.

  - `ExcludeItemBookingFromRevenueAccounting` (boolean)
    The flag to exclude rate plan charges from revenue accounting.

Note: To use this field, you must set the X-Zuora-WSDL-Version request header to 115 or later. Otherwise, an error occurs.

Note: This field is only available if you have the Billing - Revenue Integration feature enabled.

  - `Id` (string)
    Object identifier.

  - `IsLastSegment` (boolean)
    Indicates if the segment of the rate plan charge is the most recent segment. Character limit: 5 Values: automatically generated: true, false

  - `ListPriceBase` (string)
    The list price base for the product rate plan charge.
    Enum: "Per Month", "Per Billing Period", "Per Week", "Per Year", "Per Specific Months"

  - `MRR` (number)
    Monthly recurring revenue (MRR) is the amount of recurring charges in a given month. The MRR calculation doesn't include one-time charges nor usage charges. Character limit: 16 Values: automatically generated

  - `Name` (string)
    The name of the rate plan charge. Character limit: 100 Values: automatically generated

  - `NumberOfPeriods` (integer)
    Specifies the number of periods to use when calculating charges in an overage smoothing charge model. Character limit: 5 Values: inherited from ProductRatePlanCharge.NumberOfPeriod

  - `OriginalId` (string)
    The original ID of the rate plan charge. Character limit: 32 Values: automatically generated

  - `OverageCalculationOption` (string)
    Determines when to calculate overage charges. If the value of the SmoothingMode field is null (not specified and not inherited from ProductRatePlanCharge.SmoothingMode), the value of this field is ignored. Character limit: 20 Values: inherited from ProductRatePlanCharge.OverageCalculationOption

  - `OverageUnusedUnitsCreditOption` (string)
    Determines whether to credit the customer with unused units of usage.
Character limit: 20 Values: inherited from ProductRatePlanCharge.OverageUnusedUnitsCreditOption

  - `PriceChangeOption` (string)
    Applies an automatic price change when a termed subscription is renewed.
Character limit: Values: one of the following:

- NoChange (default)
- SpecificPercentageValue
- UseLatestProductCatalogPricing

  - `PriceIncreasePercentage` (number)
    Specifies the percentage to increase or decrease the price of renewed subscriptions.
Character limit: 16 Values: a decimal value between -100 and 100

  - `ProcessedThroughDate` (string)
    The date until when charges have been processed. When billing in arrears, such as usage, this field value is the the same as the ChargedThroughDate value. This date is the earliest date when a charge can be amended.
Character limit: 29 Values: automatically generated

  - `Quantity` (number)
    The default quantity of units, such as the number of authors in a hosted wiki service. Valid for all charge models except for Flat Fee pricing.
Character limit: 16 Values: a valid quantity value

  - `RatePlanId` (string)
    The ID of the rate plan associated with the rate plan charge.
Character limit: 32 Values: inherited from RatePlan.Id

  - `RatingGroup` (string)
    A rating group based on which usage records are rated. Only applicable to Usage charges.

Possible values:

- ByBillingPeriod: The rating is based on all the usages in a billing period.
- ByUsageStartDate: The rating is based on all the usages on the same usage start date. 
- ByUsageRecord: The rating is based on each usage record.
- ByUsageUpload: The rating is based on all the  usages in a uploaded usage file (.xls or .csv).
- ByGroupId: The rating is based on all the usages in a custom group.

For more information, see [Usage rating by group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group).
    Enum: "ByBillingPeriod", "ByUsageStartDate", "ByUsageRecord", "ByUsageUpload", "ByGroupId"

  - `RevRecCode` (string)
    Associates this product rate plan charge with a specific revenue recognition code.

Character limit: 70

Values: inherited from ProductRatePlanCharge.RevRecCode or a valid revenue recognition code

Note: Unless overridden, this value changes if ProductRatePlanCharge.RevRecCode is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevRecCode is updated.

  - `RevRecTriggerCondition` (string)
    Specifies when revenue recognition begins.

Character limit: 22

Values: inherited from ProductRatePlanCharge.RevRecTriggerCondition or one of the following:

-  ContractEffectiveDate

-  ServiceActivationDate

-  CustomerAcceptanceDate

Note: Unless overridden, this value changes if ProductRatePlanCharge.RevRecTriggerCondition is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevRecTriggerCondition is updated.

  - `RevenueRecognitionRuleName` (string)
    Specifies the Revenue Recognition Rule that you want the Rate Plan Charge to use. This field can be updated when Status is Draft. By default, the Revenue Recognition Rule is inherited from the Product Rate Plan Charge. For Amend calls, you can use this field only for NewProduct amendments. For Update calls, you can use this field only to update subscriptions in draft status. Note that if you use this field to specify a Revenue Recognition Rule for the Rate Plan Charge, the rule will remain as specified even if you later change the rule used by the corresponding Product Rate Plan Charge.

Character limit: n/a

Values: inherited from ProductRatePlanCharge.RevenueRecognitionRuleName or the name of an active Revenue Recognition Rule

Note: Unless overridden, this value changes if ProductRatePlanCharge.RevenueRecognitionRuleName is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevenueRecognitionRuleName is updated.

  - `RolloverBalance` (number)
    Specifies the number of units of measure (UOM) rolled over from previous periods. The value of this field is the rollover balance for the corresponding account.

This field is applicable only to usage charges with overage models.

Note:

- You cannot query or filter this field with other fields in a single query.
- To query or filter this field, you must specify and only specify the rate plan charge Id in the condition.
- You cannot use this field in the query or filter condition.

  - `Segment` (integer)
    The identifying number of the subscription rate plan segment. Segments are numbered sequentially, starting with 1.
Character limit: 2 Values: automatically generated

  - `SpecificBillingPeriod` (integer)
    Customizes the number of months or weeks for the charges billing period. This field is required if you set the value of the BillingPeriod field to Specific Months or Specific Weeks.
Character limit: 5 Values: inherited from ProductRatePlanCharge.BillingPeriod Note: You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.

  - `SpecificEndDate` (string)
    The specific date on which the charge ends, in yyyy-mm-dd format.
Character limit: 29 Note:

- This field is only applicable when the EndDateCondition field is set to SpecificEndDate.
- If the subscription ends before the specific end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the specific end date.

  - `SpecificListPriceBase` (any)
    The number of months for the list price base of the charge. The value of this field is null if you do not set the value of the ListPriceBase field to Per Specific Months.
Note:  - This field is available only if you have the Annual List Price feature enabled. - The value of this field is null if you do not set the value of the ListPriceBase field to Per Specific Months.

  - `TCV` (number)
    The total contract value (TCV) is the value of a single rate plan charge in a subscription over the lifetime of the subscription. This value does not represent all charges on the subscription. The TCV includes recurring charges and one-time charges, but it doesn't include usage charge.
Character limit: 16 Values: automatically generated

  - `TriggerDate` (string)
    The date when the charge becomes effective and billing begins, in yyyy-mm-dd format. This field is required if the TriggerEvent field value is SpecificDate.
Character limit: 29

  - `TriggerEvent` (string)
    Specifies when to start billing the customer for the charge.
Note: This field can be passed through the Subscribe and Amend calls and will override the default value set on the Product Rate Plan Charge.
Character limit: 18 Values: inherited from ProductRatePlanCharge.TriggerEvent and can be one of the following values:

- ContractEffective is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- ServiceActivation is when the services or products for a subscription have been activated and the customers have access.
- CustomerAcceptance is when the customer accepts the services or products for a subscription.
- SpecificDate is valid only on the RatePlanCharge.

  - `UOM` (string)
    Specifies the units to measure usage.
Character limit: 25 Values: inherited from ProductRatePlanCharge.UOM

  - `UpToPeriods` (integer)
    Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
Character limit: 5 Values: inherited from ProductRatePlanCharge.UpToPeriods Note:

- You must use this field together with the UpToPeriodsType field to specify the time period. This field is only applicable only when the EndDateCondition field is set to FixedPeriod.
- You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
- Use this field to override the value in ProductRatePlanCharge.UpToPeriod.
- If you override the value in this field, enter a whole number between 0 and 65535, exclusive.
- If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.

  - `UpToPeriodsType` (string)
    The period type used to define when the charge ends. This field can be updated when Status is Draft. Values: one of the following:

- Billing Periods (default)
- Days
- Weeks
- Months
- Years
Note:

- You must use this field together with the UpToPeriods field to specify the time period.
- This field is only applicable only when the EndDateCondition field is set to FixedPeriod.

  - `UpdatedById` (string)
    The ID of the last user to update the object. Character limit: 32 Values: automatically generated

  - `UpdatedDate` (string)
    The date when the object was last updated.
Character limit: 29 Values: automatically generated

  - `Version` (integer)
    The version of the rate plan charge. Each time a charge is amended, Zuora creates a new version of the rate plan charge. Character limit: 5 Values: automatically generated

  - `WeeklyBillCycleDay` (string)
    Specifies which day of the week as the bill cycle day (BCD) for the charge.
This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).

Values: one of the following:

- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday

## Response 401 fields (application/json):

  - `message` (string)
    Error message.

If the error message is "Authentication error", ensure that the Authorization request header contains valid authentication credentials, then retry the request. See [Authentication](https://developer.zuora.com/rest-api/general-concepts/authentication/) for more information.

If the error message is "Failed to get user info", retry the request.

## Response 404 fields (application/json):

  - `done` (boolean)

  - `records` (array)

  - `size` (integer)