v1

latestOpenAPI 3.0.32026-07-24614422630.2 KB

Product Catalog

Add charge to plan

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

post/plans/{planId}/charges

Path parameters

planIdstring required

ID of the plan to which you want to add the charge. To get a list of IDs, call the Get plans operation.

Request body

idstring

System-generated unique identifier for the charge

namestring required

Name of the charge

displayNamestring

Display name of the charge shown to customers

descriptionstring

Detailed description of the charge

taxRateIdstring uuid

ID of the tax rate applied to this charge. To get a list of available tax rate IDs, call the Get tax rates operation. DEPRECATED: Use taxRateStrategyId instead. (deprecated: use taxRateStrategyId)

taxRateStrategyIdstring

ID of the tax rate strategy applied to this charge. This determines how taxes are calculated when multiple tax rates apply.

unitOfMeasureIdstring 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 operation.

isRenewableboolean

Indicates if the charge is renewable

isCreditableboolean

Indicates if the charge can be credited

isListPriceEditableboolean

Indicates if the list price can be edited

minQuantityinteger

Minimum quantity that must be ordered. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.

defaultQuantityinteger

Default quantity for this charge. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.

maxQuantityinteger

Maximum quantity that can be ordered. Applicable only if the chargeModel is PER_UNIT or RATE_CARD_LOOKUP.

externalIdstring

External identifier for the charge, used for integration with other systems

minAmountnumber

NOTE: This parameter is currently in beta Minimum monetary amount for this charge. Applies only when type is PERCENTAGE_OF.

maxAmountnumber

NOTE: This parameter is currently in beta Maximum monetary amount for this charge. Applies only when type is PERCENTAGE_OF.

recognitionRuleIdstring

ID of the revenue recognition rule associated with this charge

erpIdstring

ERP system identifier for this charge

itemCodestring

Item code used for this charge in external systems

targetPlanIdsstring[]

List of plan IDs that this PERCENTAGE_OF charge applies to

planIdstring

ID of the plan this charge belongs to

amountnumber

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.

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.

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.

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.

isDrawdownboolean

Indicates if this is a drawdown charge

minimumCommitBaseChargeIdstring

ID of the base charge for minimum commit calculation

overageBaseChargeIdstring

NOTE: This parameter is currently in beta ID of the base charge for overage calculation

isCustomboolean

Indicates if this is a custom charge

percentnumber

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

durationInMonthsinteger

Duration of the charge in months (for time-limited charges)

isEventBasedboolean

Indicates if this charge is event-based rather than time-based

isDiscountboolean

Indicates if this charge represents a discount

rateCardIdstring

ID of the rate card for RATE_CARD_LOOKUP charge models

billingTerm'UP_FRONT' | 'IN_ARREARS'

Billing term: UP_FRONT or IN_ARREARS

Billing cycle: DEFAULT, CHARGE_RECURRENCE, PAID_IN_FULL, MONTH, QUARTER, SEMI_ANNUAL, YEAR

shouldTrackArrboolean

Indicates if this charge should be included in Annual Recurring Revenue (ARR) calculations

customFieldsobject

Map of custom fields associated with this charge

customboolean

eventObjectIdstring

drawdownboolean

eventBasedboolean

creditableboolean

Response

successful operation