HOW TO find effective RatePlanCharge for a particular Subscription in Zuora
Every time an amendment is applied to a Subscription, a new version of that subscription along with a copy of all of its dependent objects is created. These objects may include multiple Usages, RatePlans, RatePlanCharges, and RatePlanChargeTiers. Each these objects will get their own new Id and the amended Original Subscription's Status will be changed from Active to either Cancelled or Expired based on the changes made by the amendment.
The following objects and fields are involved:
- Fields needed in Account:
- Id | The customer account identification number.
- Fields needed in Subscription:
- Status | A list of values reflecting the status of the subscription. (Draft, Pending Activation, Pending Acceptance, Active, Cancelled, Expired).
- Fields needed in RatePlan:
- SubscriptionId | Used to cross reference Subscriptions to its respective RatePlanCharges.
- Fields needed in RatePlanCharge:
- Segment | As of version 20.0. The identifying number (order) of the segment. Segments are numbered sequentially, starting with 1.
- IsLastSegment | Available in version 24.0+ of the API. Specifies whether the Segment of RatePlanCharge is the latest segment.
- EffectiveStartDate | Available as of version 20.0. The date when the (segmented) charge starts/started.
- EffectiveEndDate | Available as of version 20.0. The date when the (segmented) charge ends/ended.
A RatePlanCharge, likeRatePlan, is part of a Subscription. Each subscription can have one or more rate plans, and each rate plan can have one or more rate plan charges. Rate plan charges are the actual charges for the services (rate plans) that you are giving, and can be of different types; for example, one-time fees, monthly recurring fees, usage fees, and so on.
Please note that as of version 20.0, Zuora returns segmented RatePlanCharges. Every time a charge is changed through an amendment, Zuora will create a new segemented RatePlanCharge. Thus, you can now quickly and easily parse a charge's history, know when price or quantity were changed, and if there are any future pending changes to a charge. By default, Zuora will now return a RatePlanCharge for each segment of the charge. With RatePlanCharge.Segment, RatePlanCharge.EffectiveEndDate and RatePlanCharge.EffectiveStartDate, you can quickly:
- Determine current price/quantity of a charge (EffectiveStartDate <= Today <= EffectiveEndDate)
- See previous states of the charge (such as price/quantity) (EffectiveEndDate < Today)
- See future, pending changes (EffectiveStartDate > Today)
- Piece together an entire charge history (Order RatePlanCharge by segments, starting with segment=1)
The following steps need to be taken to determine the effective RatePlanCharge at the time of the query:
- Identify the account in Zuora.
- Given Account.AccountNumber, query Account for Account.Id:
<ns1:query> <ns1:queryString>Select Id, from Account where AccountNumber='0000001'</ns1:queryString> </ns1:query>
2. Use SubscriptionId to query for Active Subscriptions.
- Using Account.Id and Subscription.Status, query Subscription:
<ns1:query> <ns1:queryString>Select Id, from Subscription where AccountId='xxxx0000001' and Status='Active'</ns1:queryString> </ns1:query>
3. Query RatePlan to get SubscriptionId.
- Using Subscription.Id, query RatePlan.
<ns1:query> <ns1:queryString>Select Id, from RatePlan where SubscriptionId='xxxx0000001'</ns1:queryString> </ns1:query>
4. Get the necessary information from the RatePlanCharges.
- Using RatePlan.Id, Query RatePlanCharge for Id, RatePlanId, EffectiveStartDate, EffectiveEndDate, Segment and IsLastSegment.
<ns1:query> <ns1:queryString>Select Id, RatePlanId, EffectiveStartDate, EffectiveEndDate, Segment, IsLastSegment from RatePlan where RatePlanId='xxxx0000001'</ns1:queryString> </ns1:query>
Appendix A: Graphical Representation