---
title: "Add charge to plan"
method: POST
path: "/plans/{planId}/charges"
tags: ["Product Catalog"]
---

# Add charge to plan

`POST /plans/{planId}/charges`

Adds a charge to the specified plan.  Success response contains ID of the new charge.

## Path parameters

- `planId` string, required

## Request body

- ChargeJson — JSON object representing the charge details.
  - `id` string — System-generated unique identifier for the charge
  - `name` string, required — Name of the charge
  - `displayName` string — Display name of the charge shown to customers
  - `description` string — Detailed description of the charge
  - `taxRateId` string, uuid — ID of the tax rate applied to this charge. To get a list of available tax rate IDs, call the [Get tax rates](/reference/gettaxrates) operation. DEPRECATED: Use taxRateStrategyId instead. (deprecated: use taxRateStrategyId)
  - `taxRateStrategyId` string — ID of the tax rate strategy applied to this charge. This determines how taxes are calculated when multiple tax rates apply.
  - `unitOfMeasureId` string, uuid — ID of the unit of measure for this charge (e.g., GB, users, licenses). To get a list of available unit of measure IDs, call the [Get units of measure](/reference/getunitsofmeasure) operation.
  - `isRenewable` boolean — Indicates if the charge is renewable
  - `isCreditable` boolean — Indicates if the charge can be credited
  - `isListPriceEditable` boolean — Indicates if the list price can be edited
  - `minQuantity` integer — Minimum quantity that must be ordered. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.
  - `defaultQuantity` integer — Default quantity for this charge. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.
  - `maxQuantity` integer — Maximum quantity that can be ordered. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.
  - `externalId` string — External identifier for the charge, used for integration with other systems
  - `minAmount` number — **NOTE: This parameter is currently in beta** Minimum monetary amount for this charge. Applies only when `type` is `PERCENTAGE_OF`.
  - `maxAmount` number — **NOTE: This parameter is currently in beta** Maximum monetary amount for this charge. Applies only when `type` is `PERCENTAGE_OF`.
  - `recognitionRuleId` string — ID of the revenue recognition rule associated with this charge
  - `erpId` string — ERP system identifier for this charge
  - `itemCode` string — Item code used for this charge in external systems
  - `targetPlanIds` string[] — List of plan IDs that this PERCENTAGE_OF charge applies to
  - `planId` string — ID of the plan this charge belongs to
  - `amount` number — The monetary amount for this charge
  - `type` 'ONE_TIME' | 'RECURRING' | 'USAGE' | 'PREPAID' | 'PERCENTAGE_OF', required — Type of charge: `ONE_TIME`, `RECURRING`, `USAGE`, `PREPAID`, or `PERCENTAGE_OF`. See also [Supported charge type and charge model combinations](/docs/charge-types-and-models#/supported-charge-type-and-charge-model-combinations). * `ONE_TIME`: Charge a one-time fee for a product or service that's usually purchased only once, for example, an initial setup fee. * `RECURRING`: Charge a fee on a recurring basis. The `recurrence` object specifies the cadence. * `USAGE`: Charge customers based on their usage of the product or service. * `PREPAID`: Charge customers a certain price in advance of them using a product or service. Suitable for scenarios where the customer purchases the product or service for a fixed duration or usage limit. * `PERCENTAGE_OF`: Charge a percentage of a customer's revenue gained from using your product or service. The price is calculated as a percentage of the total cost of one or more target plans. The `targetPlanIds` field specifies the plans that are targeted.
  - `chargeModel` 'PER_UNIT' | 'VOLUME' | 'TIERED' | 'FLAT_FEE' | 'BLOCK' | 'RATE_CARD_LOOKUP', required — Pricing model for the charge: `PER_UNIT`, `VOLUME`, `TIERED`, `FLAT_FEE`, `BLOCK`, or `RATE_CARD_LOOKUP`. See also [Supported charge type and charge model combinations](/docs/charge-types-and-models#/supported-charge-type-and-charge-model-combinations). * `PER_UNIT`: Charge a specific amount per unit of the product. * `VOLUME`: Offer a volume discount where per-unit cost decreases as the customer buys a larger number of product units. * `TIERED`: Define tiers with different per-unit prices based on number of units bought. Per-unit prices are applied successively starting with the first tier. * `FLAT_FEE`: Charge a fixed, flat amount on a set schedule regardless of plan usage. For example, charge a $10 flat fee per month. * `BLOCK`: Define product usage in tiered blocks and charge a specific amount per block based on the usage tier. For example, for an email marketing platform, charge $100 for a usage block of 1-500 emails, and $150 for a usage block of 500+ emails. A customer who wants to send 800 emails will purchase the 500+ block for $150. * `RATE_CARD_LOOKUP`: Use an existing rate card to price a product based on a combination of price attributes.
  - `recurrence` RecurrenceJson
    - `cycle` 'DAY' | 'MONTH' | 'QUARTER' | 'SEMI_ANNUAL' | 'YEAR' | 'PAID_IN_FULL' | 'CUSTOM', required
    - `step` integer, required
  - `priceTiers` PriceTierJson[] — List of price tiers for tiered pricing models. Required only if the value of `chargeModel` is `TIERED`, `BLOCK` or `VOLUME`.
    - `untilQuantity` string, required
    - `amount` number, required
    - `overage` number
  - `isDrawdown` boolean — Indicates if this is a drawdown charge
  - `minimumCommitBaseChargeId` string — ID of the base charge for minimum commit calculation
  - `overageBaseChargeId` string — **NOTE: This parameter is currently in beta** ID of the base charge for overage calculation
  - `isCustom` boolean — Indicates if this is a custom charge
  - `percent` number — Percentage value for PERCENTAGE_OF charge types
  - `percentDerivedFrom` 'LIST_AMOUNT' | 'SELL_AMOUNT' — For PERCENTAGE_OF charges, specifies if percentage is calculated from LIST_AMOUNT or SELL_AMOUNT
  - `ledgerAccountMapping` LedgerAccountMapping
    - `taxLiabilityAccountId` string
    - `deferredRevenueAccountId` string
    - `recognizedRevenueAccountId` string
    - `contractAssetAccountId` string
    - `ledgerAccountIds` string[]
  - `durationInMonths` integer — Duration of the charge in months (for time-limited charges)
  - `isEventBased` boolean — Indicates if this charge is event-based rather than time-based
  - `isDiscount` boolean — Indicates if this charge represents a discount
  - `rateCardId` string — ID of the rate card for RATE_CARD_LOOKUP charge models
  - `billingTerm` 'UP_FRONT' | 'IN_ARREARS' — Billing term: UP_FRONT or IN_ARREARS
  - `billingCycle` 'DEFAULT' | 'CHARGE_RECURRENCE' | 'PAID_IN_FULL' | 'MONTH' | 'QUARTER' | 'SEMI_ANNUAL' | 'YEAR' — Billing cycle: DEFAULT, CHARGE_RECURRENCE, PAID_IN_FULL, MONTH, QUARTER, SEMI_ANNUAL, YEAR
  - `shouldTrackArr` boolean — Indicates if this charge should be included in Annual Recurring Revenue (ARR) calculations
  - `customFields` object — Map of custom fields associated with this charge
  - `custom` boolean
  - `eventObjectId` string
  - `drawdown` boolean
  - `eventBased` boolean
  - `creditable` boolean

## Response `200`

successful operation

- ChargeJson — JSON object representing the charge details.
  - `id` string — System-generated unique identifier for the charge
  - `name` string, required — Name of the charge
  - `displayName` string — Display name of the charge shown to customers
  - `description` string — Detailed description of the charge
  - `taxRateId` string, uuid — ID of the tax rate applied to this charge. To get a list of available tax rate IDs, call the [Get tax rates](/reference/gettaxrates) operation. DEPRECATED: Use taxRateStrategyId instead. (deprecated: use taxRateStrategyId)
  - `taxRateStrategyId` string — ID of the tax rate strategy applied to this charge. This determines how taxes are calculated when multiple tax rates apply.
  - `unitOfMeasureId` string, uuid — ID of the unit of measure for this charge (e.g., GB, users, licenses). To get a list of available unit of measure IDs, call the [Get units of measure](/reference/getunitsofmeasure) operation.
  - `isRenewable` boolean — Indicates if the charge is renewable
  - `isCreditable` boolean — Indicates if the charge can be credited
  - `isListPriceEditable` boolean — Indicates if the list price can be edited
  - `minQuantity` integer — Minimum quantity that must be ordered. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.
  - `defaultQuantity` integer — Default quantity for this charge. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.
  - `maxQuantity` integer — Maximum quantity that can be ordered. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.
  - `externalId` string — External identifier for the charge, used for integration with other systems
  - `minAmount` number — **NOTE: This parameter is currently in beta** Minimum monetary amount for this charge. Applies only when `type` is `PERCENTAGE_OF`.
  - `maxAmount` number — **NOTE: This parameter is currently in beta** Maximum monetary amount for this charge. Applies only when `type` is `PERCENTAGE_OF`.
  - `recognitionRuleId` string — ID of the revenue recognition rule associated with this charge
  - `erpId` string — ERP system identifier for this charge
  - `itemCode` string — Item code used for this charge in external systems
  - `targetPlanIds` string[] — List of plan IDs that this PERCENTAGE_OF charge applies to
  - `planId` string — ID of the plan this charge belongs to
  - `amount` number — The monetary amount for this charge
  - `type` 'ONE_TIME' | 'RECURRING' | 'USAGE' | 'PREPAID' | 'PERCENTAGE_OF', required — Type of charge: `ONE_TIME`, `RECURRING`, `USAGE`, `PREPAID`, or `PERCENTAGE_OF`. See also [Supported charge type and charge model combinations](/docs/charge-types-and-models#/supported-charge-type-and-charge-model-combinations). * `ONE_TIME`: Charge a one-time fee for a product or service that's usually purchased only once, for example, an initial setup fee. * `RECURRING`: Charge a fee on a recurring basis. The `recurrence` object specifies the cadence. * `USAGE`: Charge customers based on their usage of the product or service. * `PREPAID`: Charge customers a certain price in advance of them using a product or service. Suitable for scenarios where the customer purchases the product or service for a fixed duration or usage limit. * `PERCENTAGE_OF`: Charge a percentage of a customer's revenue gained from using your product or service. The price is calculated as a percentage of the total cost of one or more target plans. The `targetPlanIds` field specifies the plans that are targeted.
  - `chargeModel` 'PER_UNIT' | 'VOLUME' | 'TIERED' | 'FLAT_FEE' | 'BLOCK' | 'RATE_CARD_LOOKUP', required — Pricing model for the charge: `PER_UNIT`, `VOLUME`, `TIERED`, `FLAT_FEE`, `BLOCK`, or `RATE_CARD_LOOKUP`. See also [Supported charge type and charge model combinations](/docs/charge-types-and-models#/supported-charge-type-and-charge-model-combinations). * `PER_UNIT`: Charge a specific amount per unit of the product. * `VOLUME`: Offer a volume discount where per-unit cost decreases as the customer buys a larger number of product units. * `TIERED`: Define tiers with different per-unit prices based on number of units bought. Per-unit prices are applied successively starting with the first tier. * `FLAT_FEE`: Charge a fixed, flat amount on a set schedule regardless of plan usage. For example, charge a $10 flat fee per month. * `BLOCK`: Define product usage in tiered blocks and charge a specific amount per block based on the usage tier. For example, for an email marketing platform, charge $100 for a usage block of 1-500 emails, and $150 for a usage block of 500+ emails. A customer who wants to send 800 emails will purchase the 500+ block for $150. * `RATE_CARD_LOOKUP`: Use an existing rate card to price a product based on a combination of price attributes.
  - `recurrence` RecurrenceJson
    - `cycle` 'DAY' | 'MONTH' | 'QUARTER' | 'SEMI_ANNUAL' | 'YEAR' | 'PAID_IN_FULL' | 'CUSTOM', required
    - `step` integer, required
  - `priceTiers` PriceTierJson[] — List of price tiers for tiered pricing models. Required only if the value of `chargeModel` is `TIERED`, `BLOCK` or `VOLUME`.
    - `untilQuantity` string, required
    - `amount` number, required
    - `overage` number
  - `isDrawdown` boolean — Indicates if this is a drawdown charge
  - `minimumCommitBaseChargeId` string — ID of the base charge for minimum commit calculation
  - `overageBaseChargeId` string — **NOTE: This parameter is currently in beta** ID of the base charge for overage calculation
  - `isCustom` boolean — Indicates if this is a custom charge
  - `percent` number — Percentage value for PERCENTAGE_OF charge types
  - `percentDerivedFrom` 'LIST_AMOUNT' | 'SELL_AMOUNT' — For PERCENTAGE_OF charges, specifies if percentage is calculated from LIST_AMOUNT or SELL_AMOUNT
  - `ledgerAccountMapping` LedgerAccountMapping
    - `taxLiabilityAccountId` string
    - `deferredRevenueAccountId` string
    - `recognizedRevenueAccountId` string
    - `contractAssetAccountId` string
    - `ledgerAccountIds` string[]
  - `durationInMonths` integer — Duration of the charge in months (for time-limited charges)
  - `isEventBased` boolean — Indicates if this charge is event-based rather than time-based
  - `isDiscount` boolean — Indicates if this charge represents a discount
  - `rateCardId` string — ID of the rate card for RATE_CARD_LOOKUP charge models
  - `billingTerm` 'UP_FRONT' | 'IN_ARREARS' — Billing term: UP_FRONT or IN_ARREARS
  - `billingCycle` 'DEFAULT' | 'CHARGE_RECURRENCE' | 'PAID_IN_FULL' | 'MONTH' | 'QUARTER' | 'SEMI_ANNUAL' | 'YEAR' — Billing cycle: DEFAULT, CHARGE_RECURRENCE, PAID_IN_FULL, MONTH, QUARTER, SEMI_ANNUAL, YEAR
  - `shouldTrackArr` boolean — Indicates if this charge should be included in Annual Recurring Revenue (ARR) calculations
  - `customFields` object — Map of custom fields associated with this charge
  - `custom` boolean
  - `eventObjectId` string
  - `drawdown` boolean
  - `eventBased` boolean
  - `creditable` boolean

---

[API](https://skmtc.net/dealhub/apis/quote-api.md) · [All operations](https://skmtc.net/dealhub/apis/quote-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dealhub/quote-api/versions/c30f5b9fbfab/schema)