---
title: "Create a product rate plan"
method: POST
path: "/commerce/plans"
tags: ["Commerce"]
---

# Create a product rate plan

`POST /commerce/plans`

Create a product rate plan (Plan) under an existing product.
A plan includes one or more **charges**. Each charge **must** include:
  - `name`
  - `charge_model`
  - `charge_type`
  - `bill_cycle`
  - `trigger_event`
  - `end_date_condition`
  - `pricing`

  Optional charge fields include: `unit_of_measure`, `list_price_base`, and `accounting` (with `accounting_code`, `deferred_revenue_account`, `recognized_revenue_account`).

## Headers

- `Idempotency-Key` string
- `Accept-Encoding` string
- `Content-Encoding` string
- `Zuora-Entity-Ids` string
- `Zuora-Org-Ids` string
- `Zuora-Track-Id` string

## Request body

- CreatePlanRequest
  - `product_key` string, required — The unique identifier of the product under which the plan is created.
  - `name` string, required — The name of the rate plan.
  - `start_date` string, date, required — Plan effective start date (UTC, YYYY-MM-DD).
  - `end_date` string, date, required — Plan effective end date (UTC, YYYY-MM-DD).
  - `active_currencies` string[], required — ISO currency codes enabled for this plan.
  - `charges` object[], required — The list of product rate plan charges to create under the plan.
    - `name` string, required — The name of the charge.
    - `charge_model` 'flat_fee' | 'per_unit' | 'overage' | 'volume' | 'tiered' | 'tiered_overage' | 'discount_fixed_amount' | 'discount_percentage' | 'custom_charge_model' | 'delivery' | 'minimum_commitment_true_up' | 'calculated' | 'high_water_mark_volume_pricing' | 'high_water_mark_tiered_pricing' | 'multi_attribute_pricing' | 'prerated_pricing' | 'prerated_per_unit', required — Charge model that defines how pricing is calculated.
    - `charge_type` 'one_time' | 'recurring' | 'usage', required — Charge type (recurring, usage, or one-time).
    - `unit_of_measure` string — Unit of measure for per-unit or usage charges.
    - `list_price_base` 'Per_Billing_Period' | 'Per_Month' | 'Per_Week' | 'Per_Year' | 'Per_Specific_Months' | 'Per_Validity_Period' — Optional list price base, if supported by the charge model.
    - `specific_list_price_base` number, double — Optional specific value used when `list_price_base` requires an explicit quantity (for example, number of months for `Per_Specific_Months`).
    - `pricing` union, required — Defines the pricing for the charge. Provide exactly one structure per charge model.
      - object
        - `flat_amounts` object, required — Map of currency to flat amount.
      - object
        - `unit_amounts` object, required — Map of currency to per-unit price.
      - object
        - `tiers` object[], required — Tier definitions with optional min/max caps.
          - `tier` string, required — Tier identifier.
          - `from` number, required — Lower bound (inclusive).
          - `up_to` number, nullable — Upper bound (inclusive). Null for open-ended last tier.
          - `price_format` 'price_format_flat_fee' | 'price_format_per_unit', required — Price format identifier used for the tier.
          - `unit_amounts` object — Per-unit price by currency for this tier.
          - `flat_amounts` object — Flat amount by currency for this tier (if applicable).
          - `min_amounts` object — Minimum billed amount by currency for this tier.
          - `max_amounts` object — Maximum billed amount by currency for this tier.
      - object
        - `discount_amounts` object, required — Map of currency to discount amount.
      - object
        - `discount_percentage` number, double, required — Discount percentage (e.g., 15 for 15%).
    - `bill_cycle` object, required — Defines how billing occurs for this charge.
      - `type` 'default_from_customer' | 'specific_day_of_month' | 'subscription_start_day' | 'charge_trigger_day' | 'specific_day_of_week' | 'term_start_day' | 'term_end_day', required — Determines how the billing day is selected for this charge.
      - `day_of_month` integer — Required "when type is specific_day_of_month".
      - `day_of_week` 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' — Used "when type is specific_day_of_week".
      - `period` 'bill_cycle_period_month' | 'bill_cycle_period_quarter' | 'bill_cycle_period_semi_annual' | 'bill_cycle_period_annual' | 'bill_cycle_period_eighteen_months' | 'bill_cycle_period_two_years' | 'bill_cycle_period_three_years' | 'bill_cycle_period_five_years' | 'bill_cycle_period_specific_months' | 'bill_cycle_period_subscription_term' | 'bill_cycle_period_week' | 'bill_cycle_period_specific_weeks' | 'bill_cycle_period_specific_days', required — Billing period length.
      - `period_alignment` 'align_to_charge' | 'align_to_subscription_start' | 'align_to_term_start' | 'align_to_term_end', required — How the billing period start aligns.
      - `timing` 'in_advance' | 'in_arrears' — When the charge is billed relative to the service period.
    - `end_date_condition` 'subscription_end' | 'end_date_one_time' | 'fixed_period' | 'specific_end_date', required — Defines when the charge ends.
    - `up_to_periods_type` 'billing_periods' | 'days' | 'weeks' | 'months' | 'years' — Granularity used with `end_date_condition = fixed_period` to express how long the charge remains active. When `end_date_condition = subscription_end`, this field is ignored.
    - `up_to_periods` integer — Number of periods used with `end_date_condition = fixed_period`. Combined with `up_to_periods_type` to determine the fixed duration of the charge. Ignored when `end_date_condition = subscription_end`.
    - `trigger_event` 'contract_effective' | 'service_activation' | 'customer_acceptance' | 'specific_date', required — Event that triggers the charge.
    - `accounting` AccountingRequest — Accounting fields accepted on create/update requests. Field names use snake_case. **Conditional requirement rules** - If **Allow blank Accounting Codes** = **Yes** → Accounting fields are **optional**. - If **Allow blank Accounting Codes** = **No** and the tenant **has Zuora Revenue** → **all Accounting fields except `accounting_code` are required**. - If **Allow blank Accounting Codes** = **No** and the tenant **does NOT have Zuora Revenue** → only `recognized_revenue_account` and `deferred_revenue_account` are required. These rules apply to **all operations that accept `accounting`** in the payload.
      - `accounting_code` string — An accounting code associated with the charge for reporting/ERP mapping. Typically a short code or identifier, not the GL account name.
      - `accounts_receivable_account` string — Accounts Receivable (AR) account to book invoices for this charge. Must match an existing account in the tenant's chart of accounts.
      - `accounts_receivable_account_type` string — The account type associated with `accounts_receivable_account`. Maps to the `accountsReceivableAccountType` field in the accounting object.
      - `deferred_revenue_account` string — Deferred revenue (liability) account to book revenue before recognition. Must match an existing account in the tenant's chart of accounts.
      - `deferred_revenue_accounting_type` string — Accounting method/type applied to deferred revenue. Maps to the `deferredRevenueAccountingType` field in the accounting object.
      - `recognized_revenue_account` string — The name of the account where the Account Type is "Recognized Revenue".
      - `recognized_revenue_account_type` string — The account type associated with `recognized_revenue_account`. Maps to the `recognizedRevenueAccountType` field in the accounting object.
      - `adjustment_liability_account` string — The name of the account where the Account Type is "Adjustment Liability".
      - `adjustment_liability_account_type` string — The account type associated with `adjustment_liability_account`. Maps to the `adjustmentLiabilityAccountType` field in the accounting object.
      - `adjustment_revenue_account` string — The name of the account where the Account Type is "Adjustment Revenue".
      - `adjustment_revenue_account_type` string — The account type associated with `adjustment_revenue_account`. Maps to the `adjustmentRevenueAccountType` field in the accounting object.
      - `contract_asset_account` string — The name of the account where the Account Type is "Contract Asset".
      - `contract_asset_account_type` string — The account type associated with `contract_asset_account`. Maps to the `contractAssetAccountType` field in the accounting object.
      - `contract_liability_account` string — The name of the account where the Account Type is "Contract Liability".
      - `contract_liability_account_type` string — The account type associated with `contract_liability_account`. Maps to the `contractLiabilityAccountType` field in the accounting object.
      - `contract_recognized_revenue_account` string — Recognized revenue account used specifically for contract-based recognition flows. Must match an existing account in the tenant's chart of accounts.
      - `contract_recognized_revenue_account_type` string — The account type associated with `contract_recognized_revenue_account`. Maps to the `contractRecognizedRevenueAccountType` field in the accounting object.
      - `unbilled_receivables_account` string — The name of the account where the Account Type is "Unbilled Receivables".
      - `unbilled_receivables_account_type` string — The account type associated with `unbilled_receivables_account`. Maps to the `unbilledReceivablesAccountType` field in the accounting object.

## Response `200`

OK

- CreatePlanResponse
  - `id` string, required — The unique identifier of the created plan (product rate plan).
  - `name` string, required — Plan display name.
  - `displayName` string — The display name of the plan.
  - `description` string — Free-form plan description.
  - `state` string — Current lifecycle state of the plan.
  - `startDate` string, date, required — Plan effective start date (UTC, YYYY-MM-DD).
  - `endDate` string, date, required — Plan effective end date (UTC, YYYY-MM-DD).
  - `activeCurrencies` string[], required — ISO currency codes enabled for the plan.
  - `createTime` string, date-time — Timestamp when the plan was created.
  - `updateTime` string, date-time — Timestamp when the plan was last updated.
  - `createdBy` string — User ID that created the plan.
  - `updatedBy` string — User ID that last updated the plan.
  - `productId` string — The product ID (key) this plan belongs to.
  - `productRatePlanNumber` string — Plan number
  - `customFields` object — Custom field values on the plan.
  - `attributes` object[] — Attribute metadata defined at the plan level (if any).
  - `contextFilters` object[] — Contextual filters used to limit plan applicability.
  - `entitlements` object[] — Entitlements included with the plan.
  - `externalIdSourceSystem` string — Source system identifier for external integrations.
  - `externalRateplanId` string[] — External rate plan identifiers, if any.
  - `organizationLabels` object[] — Organization-level labels associated with the plan.
  - `netsuite` object, nullable — NetSuite integration metadata (if present).
  - `productRatePlanCharges` object[] — Charges created under this plan.
    - `id` string, required — Unique identifier of the product rate plan charge (PRPC).
    - `name` string, required — Charge display name within the plan.
    - `chargeModel` string, required — Pricing model that determines how the amount is calculated.
    - `chargeType` string, required — Whether the charge recurs, rates usage, or is a one-time fee.
    - `chargeFunction` string — Internal function identifier for the charge.
    - `productRatePlanChargeNumber` string — PRPC number
    - `triggerEvent` string — Event that triggers the charge to start billing.
    - `endDateCondition` string — Rule for when the charge ends, for example, subscription_end.
    - `upToPeriodsType` string — Unit applied when charge ends after a fixed duration.
    - `upToPeriods` number — Number of periods defining fixed charge duration.
    - `listPriceBase` string — List price basis, for example, Per_Billing_Period.
    - `specificListPriceBase` number — Optional override for list price base when billing uses a specific period configuration.
    - `billCycle` object, required — How and when this charge bills within each billing period.
      - `type` string — Bill-cycle mode (inherit defaults or set specific day rules).
      - `dayOfMonth` integer — Specific bill day when type = specific_day_of_month.
      - `period` string — Billing period length, for example, bill_cycle_period_month.
      - `periodAlignment` string — How the billing period start aligns, for example, align_to_charge.
      - `timing` string — Whether the charge bills before or after the service period.
    - `accounting` AccountingResponse — Accounting fields returned by the API. `*Type` fields are derived from the tenant's chart of accounts and are read-only.
      - `accountingCode` string — An accounting code associated with the charge for reporting or ERP mapping. Typically a short code or identifier, not the GL account name.
      - `accountsReceivableAccount` string — Accounts Receivable (AR) account to book invoices for this charge. Must match an existing account in the tenant's chart of accounts.
      - `accountsReceivableAccountType` string — System-derived type/category of the AR account from the chart of accounts. Examples include "AccountsReceivable".
      - `adjustmentLiabilityAccount` string — The name of the account where the Account Type is "Adjustment Liability".
      - `adjustmentLiabilityAccountType` string — System-derived type/category of the Adjustment Liability account from the chart of accounts. Examples include "AdjustmentLiability".
      - `adjustmentRevenueAccount` string — The name of the account where the Account Type is "Adjustment Revenue".
      - `adjustmentRevenueAccountType` string — System-derived type/category of the Adjustment Revenue account from the chart of accounts. Examples include "AdjustmentRevenue".
      - `contractAssetAccount` string — The name of the account where the Account Type is "Contract Asset".
      - `contractAssetAccountType` string — System-derived type/category of the Contract Asset account from the chart of accounts.
      - `contractLiabilityAccount` string — The name of the account where the Account Type is "Contract Liability".
      - `contractLiabilityAccountType` string — System-derived type/category of the Contract Liability account from the chart of accounts. Examples include "ContractLiability".
      - `contractRecognizedRevenueAccount` string — Recognized revenue account used specifically for contract-based recognition flows. Must match an existing account in the tenant's chart of accounts.
      - `contractRecognizedRevenueAccountType` string — System-derived type/category of the Contract Recognized Revenue account from the chart of accounts.
      - `deferredRevenueAccount` string — Deferred revenue (liability) account to book revenue before recognition. Must match an existing account in the tenant's chart of accounts.
      - `deferredRevenueAccountType` string — System-derived type/category of the Deferred Revenue account from the chart of accounts.
      - `recognizedRevenueAccount` string — The name of the account where the Account Type is "Recognized Revenue".
      - `recognizedRevenueAccountType` string — System-derived type/category of the Recognized Revenue account from the chart of accounts.
      - `unbilledReceivablesAccount` string — The name of the account where the Account Type is "Unbilled Receivables".
      - `unbilledReceivablesAccountType` string — System-derived type/category of the Unbilled Receivables account from the chart of accounts.
      - `productRatePlanChargeId` string — The ID of your product rate plan charge.
    - `pricing` object, required — Default (charge-level) price configuration by model/currency.
      - `flatAmounts` object — Flat amounts by currency for flat-fee pricing.
      - `unitAmounts` object — Per-unit amounts by currency for per-unit/usage pricing.
      - `tiers` object[] — Tier definitions for tiered/volume pricing.
      - `discountAmounts` object — Fixed discount amounts by currency.
      - `discountPercentages` object — Percentage discount values by currency.
      - `minAmounts` object — Minimum charge amounts by currency.
      - `maxAmounts` object — Maximum charge amounts by currency.
      - `percentages` object — Percentage price values by currency (model-dependent).
    - `priceChangeOption` string — How price changes are applied across renewals/amendments.
    - `prorationOption` string — How proration is handled relative to tenant defaults.
    - `taxable` boolean — Whether the charge is taxable.
    - `discountOptions` object — How discount charges apply and interact with other discounts.
      - `stackedDiscount` boolean — Whether this discount stacks with other discounts.
      - `applyToBillingPeriodPartially` boolean — Whether the discount can partially align to a billing period.
      - `reflectDiscountInNetAmount` boolean — Whether discounts reduce the net amount on invoices.
      - `rollover` boolean — Whether unused discount can roll over to future periods.
    - `attributes` object[] — Attribute metadata for this charge.
    - `createdById` string — User ID that created the charge record.
    - `createdTime` string, date-time — Timestamp when the charge record was created.
    - `updatedById` string — User ID that last updated the charge record.
    - `updatedTime` string, date-time — Timestamp when the charge record was last updated.
    - `labels` object — Free-form labels/tags attached to the charge.
    - `mergedRateCards` object[] — Effective rate-card rows after merges (if any).
    - `negotiatedRateCards` object[] — Customer- or deal-specific rate-card rows.
    - `ocmJsonByCurrency` object — Offer/OCM metadata keyed by currency (internal use).
    - `productChargeDefinitions` object[] — Underlying charge definitions referenced for pricing.
    - `rateCards` object[] — Dynamic Pricing rate-card rows configured on the charge.
    - `pricingSummary` object[] — Structured price summary breakdown (if returned).
    - `pricingWaterfalls` object — Detailed pricing/waterfall breakdown (if returned).
    - `overageOptions` object — Overage settings for usage charges.
      - `includedUnits` number — Included units before overage starts.
      - `unusedUnitsCreditRates` object — Credit rates for unused units (by currency).
    - `prepaid` boolean — Indicates whether the charge is prepaid.
    - `prepayment` object — Prepayment handling and rollover behavior.
      - `rollover` boolean — Whether unused prepayment rolls over.
      - `rolloverApply` string — Order in which rollover is applied.
      - `rolloverPeriodLength` integer — Length of each rollover period.
      - `rolloverPeriods` integer — Number of rollover periods allowed.
    - `isChargeLevelMinCommit` boolean — Whether a minimum commit is enforced at the charge level.
    - `isCommitted` boolean — Indicates if the charge definition is committed/finalized.
    - `useTenantDefaultForPriceChange` boolean — Whether tenant defaults govern price change behavior.
    - `revenue` object — Revenue policy settings for this charge.
      - `excludeItemBillingFromRevenueAccounting` boolean — If true, item billing is excluded from revenue accounting.
      - `excludeItemBookingFromRevenueAccounting` boolean — If true, item booking is excluded from revenue accounting.
      - `legacyReporting` boolean — Indicator for legacy revenue reporting behaviors.
      - `revenueRecognitionRuleName` string — Name of the revenue recognition rule applied.

## Other responses

- `400` — Bad Request

---

[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)