---
title: "Create a product with plans and charges"
method: POST
path: "/commerce/products"
tags: ["Commerce"]
---

# Create a product with plans and charges

`POST /commerce/products`

Create a product in the Product Catalog with one or more plans and charges.
Charges can be usage (per-unit), recurring (flat fee), or other supported models.

## Headers

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

## Request body

- CreateProductRequest
  - `name` string, required — Product name.
  - `sku` string — The stock keeping unit (SKU) associated with the product or invoice item.
  - `product_number` string — The product number that uniquely identifies the product in the product catalog.
  - `start_date` string, date, required — Product effective start date (UTC, YYYY-MM-DD).
  - `end_date` string, date, required — Product effective end date (UTC, YYYY-MM-DD).
  - `category` 'base' | 'add_on' | 'other', required — Product category.
  - `plans` object[], required — Product rate plans to create under the product.
    - `name` string, required — Rate plan name.
    - `start_date` string, date, required — Rate plan effective start date (UTC, YYYY-MM-DD).
    - `end_date` string, date, required — Rate plan effective end date (UTC, YYYY-MM-DD).
    - `active_currencies` string[], required — ISO currency codes enabled for this plan.
    - `charges` object[], required — Charges to create under this rate plan.
      - `name` string, required — Charge name.
      - `charge_type` 'one_time' | 'recurring' | 'usage', required — Charge type.
      - `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.
      - `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' — List price base for the charge.
      - `default_quantity` number — Default quantity for this charge on subscriptions created from the plan.
      - `min_quantity` number — Minimum quantity allowed for this charge. Equivalent to the `MinQuantity` field in the legacy v1 Product Rate Plan Charge.
      - `max_quantity` number — Maximum quantity allowed for this charge. Equivalent to the `MaxQuantity` field in the legacy v1 Product Rate Plan Charge.
      - `pricing` union — Default (standard) pricing defined at the charge level. Provide exactly one structure per the 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 (volume or tiered) with optional min/max caps.
            - `tier` string, required — Tier identifier (e.g., "1", "2").
            - `from` number, required — Lower bound (inclusive).
            - `up_to` number, nullable — Upper bound (inclusive). Omit/null for open-ended last tier.
            - `price_format` 'price_format_flat_fee' | 'price_format_per_unit', required — Price format 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 — Billing configuration of the 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.
        - `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 — Length of each billing period.
        - `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.
        - `day_of_month` integer — Required if "type" is `specific_day_of_month`.
        - `day_of_week` 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' — Used when "type" is `specific_day_of_week`.
        - `specific_period` string — Optional specific period value when `period` is `bill_cycle_period_specific_months`, `bill_cycle_period_specific_weeks`, or `bill_cycle_period_specific_days`. Equivalent to `SpecificBillingPeriod` in the legacy v1 API.
      - `trigger_event` 'contract_effective' | 'service_activation' | 'customer_acceptance' | 'specific_date', required — Event that triggers the charge.
      - `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' — Unit of time used when `end_date_condition` = `fixed_period`. Maps to the duration unit (billing periods, days, weeks, months, years).
      - `up_to_periods` integer — Number of periods used when `end_date_condition` = `fixed_period`.
      - `overage_options` object — Configuration for overage smoothing and period-based overage calculation. Equivalent to `NumberOfPeriod` and related fields in the legacy v1 API.
        - `number_of_periods` number — Number of billing periods used for overage smoothing / calculation.
      - `price_increase_percentage` number, double — Percentage used when `price_change_option` is set to apply a specific percentage price increase. Equivalent to `PriceIncreasePercentage` (v1).
      - `price_change_option` 'no_change' | 'specific_percentage_value' | 'use_latest_product_catalog_pricing' — Specifies how price changes are handled for future terms when this product or rate plan is amended. Equivalent to `PriceChangeOption` in the legacy v1 API. Examples include `no_change`, `specific_percentage_value`, or `use_latest_product_catalog_pricing`.
      - `use_tenant_default_for_price_change` boolean — When true, uses the tenant-level default setting for price change behavior instead of the charge-level `price_change_option`. Equivalent to `UseTenantDefaultForPriceChange` in the legacy v1 API.
      - `discount_options` object — Discount configuration for discount charge models, including "Apply Discount To" and related settings.
        - `discount_class` string — Discount class to associate with this discount charge.
        - `stacked_discount` boolean — When true, this discount can stack with other discounts.
        - `apply_to` string[] — Charge types that this discount applies to. Mirrors the "One-Time / Recurring / Usage" checkboxes in the UI.
        - `discount_level` 'rate_plan' | 'subscription' | 'account' — Level at which the discount applies (for example, subscription-level or account-level discounts).
        - `apply_to_billing_period_partially` boolean — When true, allows the discount to apply to partial billing periods.
        - `specific_accounting_codes` boolean — When true, uses discount-specific accounting codes instead of inheriting from the discounted charges. Equivalent to `UseDiscountSpecificAccountingCode` in the legacy v1 API.
        - `reflect_discount_in_net_amount` boolean — When true, discount is reflected directly in the net amount (Apply To Charge Net Amount option in the UI).
        - `rollover` boolean — Indicates whether unused discount amounts roll over to the next billing period.
        - `apply_details` object[] — Explicit list of product charges that this discount applies to when targeting specific charges.
          - `applied_product_rate_plan_id` string — ID of the target product rate plan.
          - `applied_product_rate_plan_charge_id` string — ID of the target product rate plan 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

- CreateProductResponse — Product created with optional plans and charges.
  - `id` string, required — Unique identifier of the product.
  - `name` string, required — Product name.
  - `category` string, required — Product category, for example, base or add-on.
  - `description` string — Free-form product description.
  - `productNumber` string — The product number.
  - `sku` string — Stock keeping unit for the product.
  - `startDate` string, date, required — Product effective start date, for example, UTC, YYYY-MM-DD.
  - `endDate` string, date, required — Product effective end date, for example, UTC, YYYY-MM-DD.
  - `state` string, required — Current lifecycle state of the product.
  - `allowFeatureChanges` boolean — Whether feature changes are allowed for this product.
  - `features` object[] — List of features associated with the product.
  - `legacyFeatures` object[] — Legacy feature list retained for backward compatibility.
  - `contextFilters` object[] — Context filter rules that may restrict product availability.
  - `organizationLabels` object[] — Key/value style organizational labels applied to the product.
  - `customFields` object — Custom field values on the product.
  - `customObjects` object, nullable — Custom object payloads linked to the product, if any.
  - `dacTags` object — Data access control or categorization tags for the product.
  - `netsuite` object, nullable — NetSuite integration metadata (if present).
  - `createdBy` string — ID of the user who created the product.
  - `createdTime` string, date-time — Timestamp when the product was created.
  - `updatedBy` string — ID of the user who last updated the product.
  - `updatedTime` string, date-time — Timestamp when the product was last updated.
  - `plans` object[] — Rate plans (PRPs) defined under this product.
    - `id` string, required — Unique identifier of the product rate plan (PRP).
    - `name` string, required — Rate plan display name.
    - `displayName` string — Optional alternate display name for the plan.
    - `description` string — Free-form plan description.
    - `startDate` string, date, required — Plan effective start date (UTC, YYYY-MM-DD).
    - `endDate` string, date, required — Plan effective end date (UTC, YYYY-MM-DD).
    - `state` string — Current lifecycle state of the plan.
    - `status` string — Optional status when present in some responses.
    - `activeCurrencies` string[], required — ISO currency codes enabled for this plan.
    - `createTime` string, date-time — Timestamp when the plan was created.
    - `updateTime` string, date-time — Timestamp when the plan was last updated.
    - `createdBy` string — ID of the user who created the plan.
    - `updatedBy` string — ID of the user who last updated the plan.
    - `productId` string — ID of the parent product for this plan.
    - `productRatePlanNumber` string — The plan number.
    - `attributes` object[] — Plan-level attribute metadata.
    - `contextFilters` object[] — Context filter rules scoped to the plan.
    - `entitlements` object[] — Entitlements included with the plan.
    - `externalIdSourceSystem` string — Source system identifier for the external plan ID.
    - `externalRateplanId` string[] — External plan identifier(s) from other systems.
    - `netsuite` object, nullable — NetSuite integration metadata (if present).
    - `organizationLabels` object[] — Key/value style organizational labels on the plan.
    - `customFields` object — Custom field values on the plan.
    - `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 — The charge number.
      - `productRatePlanId` string — ID of the parent plan for this charge.
      - `triggerEvent` string — Event that triggers the charge to become billable.
      - `endDateCondition` string — Condition that determines when the charge ends.
      - `upToPeriodsType` string — Unit of time used when `endDateCondition` is `fixed_period`, for example, billing periods, days, weeks, months, or years.
      - `upToPeriods` integer — Number of periods used when `endDateCondition` is `fixed_period`.
      - `listPriceBase` string — Basis used for list pricing (if applicable).
      - `specificListPriceBase` number — Optional override for list price base when billing uses a specific period configuration.
      - `billCycle` object, required — Billing configuration of the charge.
        - `type` string — Whether the charge inherits account defaults or uses an override.
        - `dayOfMonth` integer — Day of month to bill when using a specific day schedule.
        - `period` string — Billing period length (for example, monthly).
        - `periodAlignment` string — How the billing period start aligns.
        - `timing` string — When the charge is billed relative to the service period.
      - `organizationLabels` object[] — Key/value style organizational labels on the charge.
      - `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.
      - `discountOptions` object — Discount behavior flags configured on the charge.
        - `applyDetails` object[] — List of granular discount application details.
        - `applyTo` string[] — Line item categories the discount applies to.
        - `applyToBillingPeriodPartially` boolean — Whether discount applies to partial billing periods.
        - `reflectDiscountInNetAmount` boolean — Whether to reflect discounts in the net amount fields.
        - `rollover` boolean — Whether unapplied discounts roll over.
        - `stackedDiscount` boolean — Whether multiple discounts can stack.
      - `overageOptions` object — Options governing overage behavior for usage charges.
        - `includedUnits` number — Number of units included before overages apply.
        - `unusedUnitsCreditRates` object — Credit rates for unused units by currency.
      - `prepayment` object — Prepayment configuration for the charge (if applicable).
        - `rollover` boolean — Whether unused prepaid amounts roll over.
        - `rolloverApply` string — How rollover amounts are applied.
        - `rolloverPeriodLength` integer — Length of the rollover period.
        - `rolloverPeriods` integer — Number of rollover periods.
      - `prorationOption` string — Proration behavior for partial periods.
      - `priceChangeOption` string — How price changes are applied to existing subscriptions.
      - `taxable` boolean — Whether the charge is taxable.
      - `taxMode` string — Tax mode classification (present on some responses).
      - `prepaid` boolean — Whether the charge is prepaid.
      - `isCommitted` boolean — Whether the charge is committed.
      - `isChargeLevelMinCommit` boolean — Whether a minimum commitment is enforced at the charge level.
      - `useTenantDefaultForPriceChange` boolean — Whether tenant default settings apply to price changes.
      - `labels` object — Arbitrary label metadata for the charge.
      - `attributes` object[] — Attribute metadata on the charge (if configured).
      - `customFields` object — Custom field values on the charge.
      - `createdById` string — ID of the user who created the charge.
      - `createdTime` string, date-time — Timestamp when the charge was created.
      - `updatedById` string — ID of the user who last updated the charge.
      - `updatedTime` string, date-time — Timestamp when the charge was last updated.
      - `pricing` object, required — Default (charge-level) pricing returned for the charge.
        - `adjustments` object — Price adjustments by currency or context.
        - `discountAmounts` object — Fixed discount amounts by currency.
        - `discountPercentages` object — Discount percentages by currency.
        - `flatAmounts` object — Flat fee amounts by currency.
        - `maxAmounts` object — Maximum amounts by currency (caps).
        - `minAmounts` object — Minimum amounts by currency (floors).
        - `percentages` object — Percentage values by currency for percentage models.
        - `tiers` object[] — Tier definitions for tiered/volume pricing.
        - `unitAmounts` object — Per-unit prices by currency for usage/per-unit models.
      - `pricingSummary` string[] — Textual summary of pricing for display purposes.
      - `pricingWaterfalls` object — Detailed pricing waterfall data (if available).
      - `productChargeDefinitions` object[] — Charge definition metadata linked to this PRPC.
      - `rateCards` object[] — Conditional rate card rules configured for the charge.
      - `revenue` object — Revenue recognition metadata for the charge.
        - `excludeItemBillingFromRevenueAccounting` boolean — Whether item billing is excluded from revenue accounting.
        - `excludeItemBookingFromRevenueAccounting` boolean — Whether item booking is excluded from revenue accounting.
        - `legacyReporting` boolean — Whether legacy reporting is enabled.
        - `revenueRecognitionRuleName` string — Revenue recognition rule applied to this charge.
      - `ocmJsonByCurrency` object — Offer/charge metadata keyed by currency.
      - `drawdown` object — Drawdown configuration data (if applicable).
      - `extendedPrice` object — Extended price metadata (if present).
      - `mergedRateCards` object[] — Merged/compiled rate card entries after evaluation.
      - `negotiatedRateCards` object[] — Customer-specific negotiated rate card entries.

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