Table of contents
Overview
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.
Solution
Below is a graphical representation of an account with 3 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.
RatePlanCharge
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
To determine the rateplancharge that is currently in effect foe the Subscription:
1. 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 RatePlanCharge where RatePlanId='xxxx0000001'</ns1:queryString> </ns1:query>
Related
- Subscription Charge Display
- In the subscription, under Product & Charges, you can view your charges grouped by product, trigger condition, or key statistics. You can also view the date in which the charge was invoiced through and the history for that charge.
- Subscription Views
- Use the Subscription Views area (located in the upper-right of the Subscriptions page) to quickly see the status of your subscriptions, and view subscriptions by status.
- Creating Subscriptions
- You must first create your customer accounts before you can create your subscription. Once you have a customer account, you can create subscriptions for that account in three different ways. The easiest way to create a subscription is from the Customer Accounts page. You can also create a subscription from the Subscriptions page or from a product page.
- Previewing a Subscription
- You can preview a subscription at any time (when the subscription is in draft, active, or canceled status) to see the invoice charges that will be generated by the subscription.
- Invoice Subscriptions to Different Accounts
- Using the Invoice Subscription to Different Accounts feature, you can configure a subscription in an account to be rated and billed by a billing run initiated from a different account. This is typically used to create a hierarchical billing situation for larger companies with many departments, divisions, or subsidiaries.
- Subscription and Amendment Dates
- How do I allow my customers to increase or decrease the units associated with a subscription?
- How do I amend subscriptions? (Upgrades, downgrades, add-ons)
- How do I automatically notify my customers of subscriptions coming up for renewal?
- How do I create a refund in UI and API (including shutting off a subscription)?
- How do I expire a product so that it is no longer sold?
- How do I handle free trials in Zuora?
- How do I handle subscriptions that do not auto-renew at the end of the subscription term?
- How do I properly cancel or downgrade customers to avoid issuing a credit or refund?
- How do I select from more than 15 products and rate plans when adding them to a new subscription?
- How do I set up a monthly fee and a fee for storage?
- How do I set up a per user pricing model?
- How do I stop billing a customer who discontinued their subscription?
- How do I undo a change made to a subscription (delete an amendment)?
Comments