--- title: "Retrieve a rate plan" method: GET path: "/v1/rateplans/{ratePlanId}" tags: ["Rate Plans"] --- # Retrieve a rate plan `GET /v1/rateplans/{ratePlanId}` Retrieves the detailed information about a specific subscription rate plan. - If you have the Orders feature enabled, this operation retrieves information about a subscription rate plan and the related order that has amended the rate plan. - If you have the Orders Harmonization feature enabled, this operation retrieves information about a subscription rate plan and the related order and amendment that have amended the rate plan. The returned objects may be different since amendment, order, and order action are generated asynchronously. - If all are generated, the related amendment and order, including the order action, are returned. - If not, only the related amendment may be returned before generating the order and order action. - If you are an existing Zuora Subscribe and Amend customer, this operation retrieves information about a subscription rate plan and the related amendment that has amended the rate plan. **Note:** Orders is now generally available as of Zuora Billing Release 284 (August 2020). If you are an existing Zuora Subscribe and Amend customer and want to adopt Orders, see What is Orders Harmonization and join the Orders Harmonization community group for more information. If you want to enable Orders, submit a request at Zuora Global Support. **Note:** You can only retrieve information about the following order actions: - `addProduct` - `updateProduct` - `removeProduct` - `changePlan` ## Path parameters - `ratePlanId` string, string, required ## Headers - `Accept-Encoding` string - `Content-Encoding` string - `Zuora-Track-Id` string - `Zuora-Entity-Ids` string - `Zuora-Org-Ids` string - `Zuora-Version` string ## Response `200` OK - GetOrderActionRatePlanResponse - `processId` string — The ID of the process that handles the operation. - `reasons` object[] — The container of the error code and message. This field is available only if the `success` field is `false`. - `code` string — The error code of response. - `message` string — The detail information of the error response - `requestId` string, uuid — Unique identifier of the request. - `success` boolean — Indicates whether the call succeeded. - `amendment` OrderActionRatePlanAmendment — The amendment that is related to the subscription rate plan. - `code` string — The amendment code. - `contractEffectiveDate` string, date — The date when the amendment becomes effective for billing purposes, as `yyyy-mm-dd`. - `createdBy` string — The ID of the user who created this amendment. - `createdDate` string, datetime — The time that the amendment gets created in the system, in the `YYYY-MM-DD HH:MM:SS` format. - `customerAcceptanceDate` string, date — The date when the customer accepts the amendment changes to the subscription, as `yyyy-mm-dd`. - `description` string, nullable — Description of the amendment. - `effectiveDate` string, date — The date when the amendment changes take effective. - `id` string — The amendment ID. - `name` string — The name of the amendment. - `serviceActivationDate` string, date — The date when service is activated, as `yyyy-mm-dd`. - `type` string — Type of the amendment. Possible values are: - NewProduct - RemoveProduct - UpdateProduct - `updatedBy` string — The ID of the user who updated this amendment. - `updatedDate` string, datetime — The time that the amendment gets updated in the system, in the `YYYY-MM-DD HH:MM:SS` format. - `customFields` object — Container for custom fields of an Amendment object. - `externallyManagedPlanId` string — 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. - `id` string — Unique subscription rate-plan ID. - `lastChangeType` string — Latest change type. Possible values are: - New - Update - Remove - `order` OrderActionRatePlanOrder — The order that is related to the subscription rate plan. - `id` string — The order ID. - `orderActions` OrderActionRatePlanOrderAction[] - `addProduct` OrderActionRatePlanRatePlanOverride — Rate plan associated with a subscription. - `chargeOverrides` OrderActionRatePlanChargeOverride[] — List of charges associated with the rate plan. - `billing` object — Billing information about the charge. - `billCycleDay` integer — Day of the month that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofMonth`. - `billCycleType` 'DefaultFromCustomer' | 'SpecificDayofMonth' | 'SubscriptionStartDay' | 'ChargeTriggerDay' | 'SpecificDayofWeek' — Specifies how Zuora determines the day that each billing period begins on. * `DefaultFromCustomer` - Each billing period begins on the bill cycle day of the account that owns the subscription. * `SpecificDayofMonth` - Use the `billCycleDay` field to specify the day of the month that each billing period begins on. * `SubscriptionStartDay` - Each billing period begins on the same day of the month as the start date of the subscription. * `ChargeTriggerDay` - Each billing period begins on the same day of the month as the date when the charge becomes active. * `SpecificDayofWeek` - Use the `weeklyBillCycleDay` field to specify the day of the week that each billing period begins on. - `billingPeriod` 'Month' | 'Quarter' | 'Semi_Annual' | 'Annual' | 'Eighteen_Months' | 'Two_Years' | 'Three_Years' | 'Five_Years' | 'Specific_Months' | 'Subscription_Term' | 'Week' | 'Specific_Weeks' — Billing frequency of the charge. The value of this field controls the duration of each billing period. If the value of this field is `Specific_Months` or `Specific_Weeks`, use the `specificBillingPeriod` field to specify the duration of each billing period. - `billingPeriodAlignment` 'AlignToCharge' | 'AlignToSubscriptionStart' | 'AlignToTermStart' — Specifies how Zuora determines when to start new billing periods. You can use this field to align the billing periods of different charges. * `AlignToCharge` - Zuora starts a new billing period on the first billing day that falls on or after the date when the charge becomes active. * `AlignToSubscriptionStart` - Zuora starts a new billing period on the first billing day that falls on or after the start date of the subscription. * `AlignToTermStart` - For each term of the subscription, Zuora starts a new billing period on the first billing day that falls on or after the start date of the term. See the `billCycleType` field for information about how Zuora determines the billing day. **Note**: This field is not supported in one time charges. - `billingTiming` 'IN_ADVANCE' | 'IN_ARREARS' — Specifies whether to invoice for a billing period on the first day of the billing period (billing in advance) or the first day of the next billing period (billing in arrears). - `specificBillingPeriod` integer — Duration of each billing period in months or weeks, depending on the value of the `billingPeriod` field. Only applicable if the value of the `billingPeriod` field is `Specific_Months` or `Specific_Weeks`. - `weeklyBillCycleDay` 'Sunday' | 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' — Day of the week that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofWeek`. - `chargeNumber` string — Charge number of the charge. For example, C-00000307. If you do not set this field, Zuora will generate the charge number. - `customFields` OrderActionRatePlanRatePlanChargeObjectCustomFields — Container for custom fields of a Rate Plan Charge object. - `description` string — Description of the charge. - `endDate` OrderActionRatePlanEndConditions — Specifies when a charge becomes inactive. - `endDateCondition` 'Subscription_End' | 'Fixed_Period' | 'Specific_End_Date' — Condition for the charge to become inactive. If the value of this field is `Fixed_Period`, the charge is active for a predefined duration based on the value of the `upToPeriodsType` and `upToPeriods` fields. If the value of this field is `Specific_End_Date`, use the `specificEndDate` field to specify the date when then charge becomes inactive. - `specificEndDate` string, date — Date in YYYY-MM-DD format. Only applicable if the value of the `endDateCondition` field is `Specific_End_Date`. - `upToPeriods` integer — Duration of the charge in billing periods, days, weeks, months, or years, depending on the value of the `upToPeriodsType` field. Only applicable if the value of the `endDateCondition` field is `Fixed_Period`. - `upToPeriodsType` 'Billing_Periods' | 'Days' | 'Weeks' | 'Months' | 'Years' — Unit of time that the charge duration is measured in. Only applicable if the value of the `endDateCondition` field is `Fixed_Period`. - `pricing` object — Pricing information about the charge. - `chargeModelData` OrderActionRatePlanChargeModelDataOverride — Container for charge model configuration data. **Note**: This field is only available if you have the High Water Mark, Pre-Rated Pricing, or Multi-Attribute Pricing charge models enabled. The charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information. - … - `discount` OrderActionRatePlanDiscountPricingOverride — Pricing information about a discount charge. - … - `oneTimeFlatFee` OrderActionRatePlanOneTimeFlatFeePricingOverride — Pricing information about a one-time charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price. - … - `oneTimePerUnit` OrderActionRatePlanOneTimePerUnitPricingOverride — Pricing information about a one-time charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased. - … - `oneTimeTiered` OrderActionRatePlanOneTimeTieredPricingOverride — Pricing information about a one-time charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased. - … - `oneTimeVolume` OrderActionRatePlanOneTimeVolumePricingOverride — Pricing information about a one-time charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased. - … - `recurringDelivery` OrderActionRatePlanRecurringDeliveryPricingOverride — Pricing information about a recurring charge that uses the Delivery Pricing charge model. In this charge model, the charge has a fixed price. This field is only available if you have the Delivery Pricing charge model enabled. - … - `recurringFlatFee` OrderActionRatePlanRecurringFlatFeePricingOverride — Pricing information about a recurring charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price. - … - `recurringPerUnit` OrderActionRatePlanRecurringPerUnitPricingOverride — Pricing information about a recurring charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased. - … - `recurringTiered` OrderActionRatePlanRecurringTieredPricingOverride — Pricing information about a recurring charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased. - … - `recurringVolume` OrderActionRatePlanRecurringVolumePricingOverride — Pricing information about a recurring charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased. - … - `usageFlatFee` OrderActionRatePlanUsageFlatFeePricingOverride — Pricing information about a usage charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price. - … - `usageOverage` OrderActionRatePlanUsageOveragePricingOverride — Pricing information about a usage charge that uses the "overage" charge model. In this charge model, the charge has an allowance of free units and a fixed price per additional unit consumed. - … - `usagePerUnit` OrderActionRatePlanUsagePerUnitPricingOverride — Pricing information about a usage charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit consumed. - … - `usageTiered` OrderActionRatePlanUsageTieredPricingOverride — Pricing information about a usage charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed. - … - `usageTieredWithOverage` OrderActionRatePlanUsageTieredWithOveragePricingOverride — Pricing information about a usage charge that uses the "tiered with overage" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed. The charge also has a fixed price per unit consumed beyond the limit of the final tier. - … - `usageVolume` OrderActionRatePlanUsageVolumePricingOverride — Pricing information about a usage charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are consumed. - … - `productRatePlanChargeId` string, required — Internal identifier of the product rate plan charge that the charge is based on. - `revRecCode` string — Revenue Recognition Code - `revRecTriggerCondition` 'Contract Effective Date' | 'Service Activation Date' | 'Customer Acceptance Date' — Specifies the revenue recognition trigger condition. * `Contract Effective Date` * `Service Activation Date` * `Customer Acceptance Date` - `revenueRecognitionRuleName` 'Recognize upon invoicing' | 'Recognize daily over time' — Specifies the revenue recognition rule. * `Recognize upon invoicing` * `Recognize daily over time` - `startDate` OrderActionRatePlanTriggerParams — Specifies when a charge becomes active. - `specificTriggerDate` string, date — Date in YYYY-MM-DD format. Only applicable if the value of the `triggerEvent` field is `SpecificDate`. While this field is applicable, if this field is not set, your `CreateSubscription` order action creates a `Pending` order and a `Pending Acceptance` subscription. If at the same time the service activation date is required and not set, a `Pending Activation` subscription is created. While this field is applicable, if this field is not set, the following order actions create a `Pending` order but do not impact the subscription status. **Note**: This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/). * AddProduct * UpdateProduct * RemoveProduct * RenewSubscription * TermsAndConditions - `triggerEvent` 'ContractEffective' | 'ServiceActivation' | 'CustomerAcceptance' — Condition for the charge to become active. If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active. - `uniqueToken` string — Unique identifier for the charge. This identifier enables you to refer to the charge before the charge has an internal identifier in Zuora. For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the charge. Then when you update the product, you can use the same unique identifier to specify which charge to modify. - `customFields` OrderActionRatePlanRatePlanObjectCustomFields — Container for custom fields of a Rate Plan object. - `newRatePlanId` string — Internal identifier of the rate plan. - `productRatePlanId` string, required — Internal identifier of the product rate plan that the rate plan is based on. - `uniqueToken` string — Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora. For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the rate plan. Then when you update the product, you can use the same unique identifier to specify which rate plan to modify. - `id` string — The Id of the order action processed in the order. - `removeProduct` OrderActionRatePlanRemoveProduct — Information about an order action of type `RemoveProduct`. - `ratePlanId` string — Internal identifier of the rate plan to remove. - `uniqueToken` string — A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, you would assign a unique token to the product rate plan when added and use that token in future order actions.A unique string in the order to represent the rate plan. - `type` 'AddProduct' | 'UpdateProduct' | 'RemoveProduct' — Type of the order action. - `updateProduct` OrderActionRatePlanRatePlanUpdate — Information about an order action of type `UpdateProduct`. - `chargeUpdates` OrderActionRatePlanChargeUpdate[] - `billing` OrderActionRatePlanBillingUpdate - `billingPeriodAlignment` 'AlignToCharge' | 'AlignToSubscriptionStart' | 'AlignToTermStart' - `chargeNumber` string — Read only. Identifies the charge to be updated. - `customFields` OrderActionRatePlanRatePlanChargeObjectCustomFields — Container for custom fields of a Rate Plan Charge object. - `description` string — Description of the charge. - `effectiveDate` OrderActionRatePlanTriggerParams — Specifies when a charge becomes active. - `specificTriggerDate` string, date — Date in YYYY-MM-DD format. Only applicable if the value of the `triggerEvent` field is `SpecificDate`. While this field is applicable, if this field is not set, your `CreateSubscription` order action creates a `Pending` order and a `Pending Acceptance` subscription. If at the same time the service activation date is required and not set, a `Pending Activation` subscription is created. While this field is applicable, if this field is not set, the following order actions create a `Pending` order but do not impact the subscription status. **Note**: This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/). * AddProduct * UpdateProduct * RemoveProduct * RenewSubscription * TermsAndConditions - `triggerEvent` 'ContractEffective' | 'ServiceActivation' | 'CustomerAcceptance' — Condition for the charge to become active. If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active. - `pricing` OrderActionRatePlanPricingUpdate - `chargeModelData` OrderActionRatePlanChargeModelDataOverride — Container for charge model configuration data. **Note**: This field is only available if you have the High Water Mark, Pre-Rated Pricing, or Multi-Attribute Pricing charge models enabled. The charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information. - … - `discount` OrderActionRatePlanDiscountPricingUpdate - … - `recurringDelivery` OrderActionRatePlanRecurringDeliveryPricingUpdate - … - `recurringFlatFee` OrderActionRatePlanRecurringFlatFeePricingUpdate - … - `recurringPerUnit` OrderActionRatePlanRecurringPerUnitPricingUpdate - … - `recurringTiered` OrderActionRatePlanRecurringTieredPricingUpdate - … - `recurringVolume` OrderActionRatePlanRecurringVolumePricingUpdate - … - `usageFlatFee` OrderActionRatePlanUsageFlatFeePricingUpdate - … - `usageOverage` OrderActionRatePlanUsageOveragePricingUpdate - … - `usagePerUnit` OrderActionRatePlanUsagePerUnitPricingUpdate - … - `usageTiered` OrderActionRatePlanUsageTieredPricingUpdate - … - `usageTieredWithOverage` OrderActionRatePlanUsageTieredWithOveragePricingUpdate - … - `usageVolume` OrderActionRatePlanUsageVolumePricingUpdate - … - `uniqueToken` string — A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, you would assign a unique token to the product rate plan when added and use that token in future order actions. - `customFields` OrderActionRatePlanRatePlanObjectCustomFields — Container for custom fields of a Rate Plan object. - `newRatePlanId` string — Internal identifier of the updated rate plan in the new subscription version. - `ratePlanId` string — Internal identifier of the rate plan that was updated. - `specificUpdateDate` string, date, nullable — The specific date when the Update Product order action takes effect. This field allows you to update a charge before a future-dated Update Product order action on the subscription. The format of the date is yyyy-mm-dd. **Note**: After you use this option, the charge's `TriggerEvent` field value will be changed to `SpecificDate`. See [Update a Product on Subscription with Future-dated Updates](https://docs.zuora.com?resourceId=billing-update-products-on-subscriptions-future-dated-updates) for more information about this feature. - `uniqueToken` string, nullable — A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, you would assign a unique token to the product rate plan when added and use that token in future order actions. - `customFields` OrderActionRatePlanOrderActionObjectCustomFields — Container for custom fields of an Order Action object. - `orderNumber` string — The order number of the order. - `productId` string — Product ID - `productName` string — The name of the product. - `productRatePlanId` string — Product rate plan ID - `productSku` string — The unique SKU for the product. - `ratePlanName` string — The name of the rate plan. - `subscriptionId` string — Subscription ID. - `subscriptionVersion` unknown ## Other responses - `500` — Internal Server Error - `4XX` — Request Errors --- [API](https://skmtc.dev/zuora/apis/api-reference.md) · [All operations](https://skmtc.dev/zuora/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zuora/api-reference/revisions/d11e237f3e54/schema)