Skip to main content

ProductRatePlan

Zuora

ProductRatePlan

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:

productrateplan-diagram.png

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

The set of {Product objectsProductRatePlan 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 notesWSDL 20.0+
Valuesautomatically 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: --
Valuesa 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: --
Valuesa 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
Valuesautomatically 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: --
Valuesautomatically 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
Valuesa 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+
Valuesautomatically generated

UpdatedDate optional

Query
Filter

The date when the object was last updated.

Type: dateTime
Character limit: 29
Version notes: --
Valuesautomatically 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.