Every time you create an amendment for 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 rate plans, rate plan charges, and rate plan charge tiers. Each of these objects will get their own new Id and the amended original subscription’s status will be changed to "expired." As an example, this outlined procedure can be used on a customer portal to show the current state of a customer's subscription.
Below is a graphical representation of an account with three versions of its subscription:
The following objects and fields will be used to help determine the current rate plan charges and map back to active subscriptions:
- 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 (for example: 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.
Note: this is intended for API versions 24 and above.
A rateplancharge, like rateplan, 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.
Every time a charge is changed through an amendment, Zuora will create a new segmented rateplancharge. For example, If you have a subscription with an annual charge that has an EffectiveStartDate = January 1, EffectiveEndDate = December 31, and then you have an amendment in the middle of the effective dates, on June 1, you would have 2 segments. Segment 1 with effective dates January 1 to May 31 and segment 2 with effective dates June 1 to December 31. 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. You can use RatePlanCharge.Segment, RatePlanCharge.EffectiveEndDate, and RatePlanCharge.EffectiveStartDate to 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)
Determining the Effective RatePlanCharge
- 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>
- 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>
- 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>
- 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 RatePlanCharge where RatePlanId='xxxx0000001'</ns1:queryString> </ns1:query>