ProductRatePlan

Last updated
Save as PDF

A product rate plan is the part of a product that your customers subscribe to. Each product can have multiple product rate plans, and each product rate plan can have multiple product rate plan charges, which are fees for products and their product rate plans.

Don't confuse a product rate plan and a rate plan. A product rate plan is a rate plan that's part of a product in your product catalog. A rate plan is the specific rate plan in a subscription.

Use the ProductRatePlan object to define the services that make up the Product objects that can be associated with Subscription objects. Topaz, Ruby, and Diamond are examples of product rate plans in the following diagram:

For more information on this example, review the Product object.

The set of {Product objects, ProductRatePlan objects, ProductRatePlanCharge objects} is a defined set of products that a company sells, such as in the example, Family Plan, Topaz level.

Supported calls

You can use this object with the following calls:

Walkthroughs and use cases

Here are some common ways to use this object:

Add a product rate plan to a product.
Modify a product rate plan in a product.
Subscribe customers to different product rate plans in the same product,

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
ActiveCurrencies	optional	Create Query Update Delete	A comma-separated list of 3-letter currency codes representing active currencies for this rate plan, e.g., "`USD, EUR, CAD, GBP`". Type: string Character limit: (see below) Version notes: WSDL 46.0+ Values: valid currency codes enabled in your tenant settings This field cannot be queried in conjunction with any other fields except `id`, and it cannot be used to modify the status of more than four currencies in a single call. Both of these are discussed in more detail below.
CreatedById	optional	Query Filter	The ID of the Zuora user who created the `ProductRatePlan` object. Type: zns:ID Character limit: 32 Version notes: WSDL 20.0+ Values: automatically generated
CreatedDate	optional	Query Filter	The date when the `ProductRatePlan` object was created. Type: dateTime Character limit: 29 Version notes: WSDL 20.0+ Values: automatically generated
Description	optional	Create Query Update Delete Filter	A description of the product rate plan. Type: string Character limit: 500 Version notes: -- Values: a string of 500 characters or fewer
EffectiveEndDate	required	Create Query Update Delete Filter	The date when the product rate plan expires and can't be subscribed to. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Character limit: 29 Version notes: -- Values: a valid date and time value
EffectiveStartDate	required	Create Query Update Delete Filter	The date when the product rate plan becomes available and can be subscribed to. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Character limit: 29 Version notes: -- Values: a valid date and time value
Grade	optional	Create Query Update Delete Filter	The grade that is assigned for the product rate plan. The value of this field must be a positive integer. The greater the value, the higher the grade. A product rate plan to be added to a Grading catalog group must have one grade. You can specify a grade for a product rate plan in this request or update the product rate plan indvidually. Type: number Character limit: -- Version notes: 116 or later Values: automatically generated
Id	optional	Query Filter	The ID of this object. Upon creation, the ID of this object is `ProductRatePlanId`. Type: zns:ID Character limit: 32 Version notes: -- Values: automatically generated
Name	required	Create Query Update Delete Filter	The name of the product rate plan. The name doesn't have to be unique in a Product Catalog, but the name has to be unique within a product. Type: string Character limit: 100 Version notes: -- Values: a string of 100 characters or fewer
ProductId	optional	Create Query Delete Filter	The ID of the product that contains the product rate plan. Type: zns:ID Character limit: 32 Version notes: Values: a string of 32 characters or fewer
ProductRatePlanNumber	optional	Create Update Query	The natural key of the product rate plan. For existing objects that were created before this field was introduced, this value will be null. Use this field in the CRUD: Update a product rate plan operation to specify a value. Zuora also provides a tool to help you automatically backfill this field with tenant ID for your existing product catalog. If you want to use this backfill tool, contact Zuora Global Support. Type: string Character limit: 100 Values: one of the following: leave null for automatically generated string an alphanumeric string of 100 characters or fewer Version notes: WSDL 133.0+
UpdatedById	optional	Query Filter	The ID of the last user to update the object. Type: zns:ID Character limit: 32 Version notes: WSDL 20.0+ Values: automatically generated
UpdatedDate	optional	Query Filter	The date when the object was last updated. Type: dateTime Character limit: 29 Version notes: -- Values: automatically generated

Additional Field Detail

ActiveCurrencies

Queries

You can query the contents of the ActiveCurrencies field and the id field, using a WHERE clause that specifies the rate plan id, as shown here:

Select id,ActiveCurrencies from ProductRatePlan where id='402892b43d909624013d90ae7f030002'

In effect, this allows you to discover the active currencies for the specified rate plan. However, you cannot query ActiveCurrencies and any other fields (besides id) at the same time.

Number of currencies

There is no practical limit on the number of active currencies (or the size of the ActiveCurrencies field), but the maximum number of codes that can be changed in a single call is four. For instance, in a single call you could activate four currencies, or deactivate four currencies, or activate two and deactivate two. To make more than four changes always requires more than one call.

The create() call creates a new ProductRatePlan with up to four active currencies. A query() at any time returns the current list of active currencies. And if an update() call includes the ActiveCurrencies field, that field should include the desired list of active currencies, always remembering that the new list can never have more than four differences from the existing list.

The update() call expects the full list of active currencies you want, not just incremental changes. For each active currency update, provide the following currencies in your list:

Current active currencies + up to four changes (additions or deletions)

SOAP API Example:

If you have four existing active currencies (AED, AFN, ALL, AMD) and you want to add four more currencies (BAM, BBD, BDT, BGN), the call would look like this:

```
<ns1:update>
 <ns1:zObjects xsi:type="ns2:ProductRatePlan">
  <ns2:Id>4028e6963087b8f201308cdbddc04228</ns2:Id>
  <ns2:ActiveCurrencies>AED,AFN,ALL,AMD,BAM,BBD,BDT,BGN</ns2:ActiveCurrencies>
 </ns1:zObjects>
</ns1:update>
```

The following table shows an example for a series of calls and the result.

Call	Operation	ActiveCurrencies field value	Active currencies after the call
create()	Create a new `DataRatePlan` object with 4 active currencies	AED, AFN, ALL, AMD	AED, AFN, ALL, AMD
update()	Activate 4 more currencies	AED, AFN, ALL, AMD, BAM, BBD, BDT, BGN	AED, AFN, ALL, AMD, BAM, BBD, BDT, BGN
update()	Deactivate 2, and activate 2 more	AED, AFN, ALL, BAM, BBD, BDT, CAD, CDF	AED, AFN, ALL, BAM, BBD, BDT, CAD, CDF

id

The id field contains the unique ID of this object, automatically assigned by Zuora 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 ProductRatePlan object is ProductRatePlanId.