Skip to main content

RatePlan

Zuora

RatePlan

A rate plan is part of a subscription or an amendment to a subscription, and it comes from a product rate plan. Like a product and its product rate plans, a subscription can have one or more rate plans. Rate plans are sometimes called subscription rate plans. Rate plans that are part of an amendment are sometimes called amendment rate plans.

Rate plans represent a price or a collection of prices for a service you sell. An individual rate plan contains all charges specific to a particular subscription.

Use a RatePlan object to create a Subscription object-specific structure of pricing and terms. You can think of a ProductRatePlan object as a template for creating a subscription. The Subscription object's individual RatePlan objects are constructed from the ProductRatePlan "template." Typically, the terms of a RatePlan object mimic its corresponding ProductRatePlan object closely. However, you can alter the terms on an individual subscription basis using the subscription's rate plan.

A RatePlan object can have multiple RatePlanCharge objects, which can be one-time fees, recurring fees, or usage fees.

A one-time fee is a charge that your customer pays only once. One-time fees don't recur. Upfront setup fees and activation fees are examples of a one-time fee.

A recurring fee is a fee that repeats on a regular basis. You can set the schedule to be monthly, quarterly, semi-annually, or annually. Once the charge is triggered, the customer is automatically charged on the appropriate dates in the future. Monthly charges for satellite TV and  yearly charges for authoring licenses on a hosted wiki are examples of a recurring fee.

A usage fee is a fee based on the amount of units, such as media storage, that customers use during a given billing period. Usage charges are billed in arrears based on a customer's actual usage. Per-minute charges for phone calls and GB of media storage are examples of usage fees.

Supported calls

You can use this object with the following calls:

Walkthroughs and use cases

Here are some common ways to use this object:

  • Query for a rate plan that's been removed
  • Add a rate plan to a subscription
  • Amend a subscription's rate plan

Field Descriptions

All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.

Name Required to Create? Allowed
Operations
Description
AmendmentId optional

Query
Filter

The ID of the amendment associated with the rate planThis field only applies to amendment rate plans.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: a valid amendment ID

AmendmentSubscriptionRatePlanId optional

Create
Query
Update
Delete
Filter

The ID of the subscription rate plan modified by the amendment. This field only applies to amendment rate plans.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid rate plan ID

AmendmentType optional

Query
Filter

The type of amendment associated with the rate plan. This field only applies to amendment rate plans.

Typestring
Character limit: 20
Version notes: --
Values: a valid amendment type

CreatedById optional

Query
Filter

The ID of the Zuora user who created the RatePlan object.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

CreatedDate optional

Query
Filter

The date when the RatePlan object was last updated.

Type: dateTime
Character limit: 29
Version notes: WSDL 20.0+
Values: automatically generated

ExternallyManagedPlanId optional Create
Query
Update

The unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.

Type: string
Character limit: 32
Version notes: --

Id optional Query
Filter
The ID of this object. Upon creation, the ID of this object is RatePlanId.

Type: zns:ID
Character limit: 32
Version notes: --
Values: automatically generated

InvoiceOwnerId required Query

The invoice owner ID of the subscription that the rate plan belongs to.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid account ID

Name required

Query
Filter

The name of the rate plan.

Typestring
Character limit: 100
Version notes: --
Values: a string of 100 characters or fewer

OriginalRatePlanId required

Query
 

The ID of the original subscription rate plan, which is the rate plan ID of the version-1 subscription.

Typezns:ID
Character limit: 32
Version notes: WSDL 136.0+
Version notes: --
Values: a valid subscription rate plan ID

ProductRatePlanId required

Query
Filter

The ID of the associated product rate plan.

Typezns:ID
Character limit: 32
Version notes: --
Values: a valid product rate plan ID

SubscriptionId required

Query
Filter

The ID of the subscription that the rate plan belongs to.

Typezns:ID
Character limit: 32
Version notes: --
Values: a valid subscription ID

SubscriptionOwnerId required Query

The subscription owner ID of the subscription that the rate plan belongs to.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid account ID

UpdatedById optional

Query
Filter

The ID of the user who last updated the rate plan.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

UpdatedDate optional

Query
Filter

The date when the rate plan was last updated.

Type: dateTime
Character limit: 29
Version notes: WSDL 20.0+
Values: automatically generated

cf_txtn__c optional

Create
Subscribe
Amend
Update

One or more custom fields.
cf_pkn__c optional Create
Subscribe
Amend
Update
One or more custom fields.

Additional Field Detail

Here's more information we think you might like to have about some of these fields. Use the Comments form at the bottom of this page if you have more questions.

AmendmentType

The type of amendment associated with the rate planThis field only applies to amendment rate plans, which are rate plans that are part of amendments.

The value for this field is inherited from the Type field in the Amendment object, which can have the following values:

  • Cancellation
  • NewProduct
  • OwnerTransfer
  • RemoveProduct
  • Renewal
  • TermsAndConditions
  • UpdateProduct

Id

The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscription object's ID with the call.

The ID for the RatePlan object is RatePlanId.

SubscriptionId

The ID of the subscription that the rate plan belongs to. A subscription has a one-to-many relationship with rate plans. When you create a subscription, the product rate plans that you select for it are stored as subscription rate plans.

Examples

Querying for Rate Plans (including Removed RatePlans)

By default, rate plans that were removed by an amendment with the type, Remove Product Amendment, aren't returned by queries. 

If you want to return rate plans that were removed by an amendment, add AmendmentType != null in the where clause conditions.

For example, the following query will return two RatePlans. One of the RatePlans was previously removed by an amendment.

select Id, SubscriptionId, AmendmentType, Name from RatePlan Where AmendmentType!=null and SubscriptionId = '4028e4883294aa9c013296255d7b2a83'

The following query will return one RatePlan, which is included in the latest subscription.

select Id, SubscriptionId, AmendmentType, Name from RatePlan Where SubscriptionId = '4028e4883294aa9c013296255d7b2a83'