Understand Customer Price

Each product in the Cleverbridge platform has one or more prices defined on the Base Price tab.
Each price includes:

Attribute	Description
`Currency`	ISO currency code for the product price.
`Taxes`	Determines whether taxes are included in or added to the product price.
`Price`	Product price for the specified currency.

Set base price

Override default price

By default, subscription items use the prices configured for the product in the Cleverbridge platform.

To set a different price for a subscription item, use one of the following Subscription API endpoints:

These endpoints include a CustomerPrice parameter, which consists of the following required subparameters:

Subparameter	Type	Required	Example	Notes
Currency	str	Yes	EUR	ISO ID for the currency
IsGross	bool	Yes	true	Determines whether the price is gross or net
Value	int	Yes	9.99	The new price amount for the item

Use the Currency Subparameter

The Currency value must match the currency of the subscription.

If the currency does not match, the request fails and the following error is returned:

'CustomerPrice' currency differs from subscription currency

Use the IsGross Subparameter

On the Cleverbridge platform, the Taxes settings on the Base Price tab govern how taxes are applied to a product purchase.

When using the Subscription API, set IsGross to match the product's Taxes setting in the Cleverbridge platform:

If	Set to
`Taxes = Gross`	`IsGross=true`
`Taxes = Net`	`IsGross=false`

🚧
Important
If IsGross is not set consistently with the Cleverbridge platform product setup, the Subscription API can have a significant impact on both the customer price and client revenue.

Example

The example below illustrates how setting IsGross inconsistently can produce unintended results.

Assume that a product priced at US$150.00 has been set up in the Cleverbridge platform with its Taxes setting set to Net (taxes should be added to the $15.00 price).

Price calculation

Assume that a product is priced at US$150.00 and configured with the Taxes setting set to Net, meaning taxes are added on top of the product price.

The following table compares the resulting price calculations when IsGross is set to true versus false.

Description	`IsGross=true` Inconsistent with product setup	`IsGross=false` Consistent with product setup
VAT tax (19%)	$24.00	$28.50
Gross price charged to the customer	$150.00	$178.50
Product price passed in the API call	$150.00	$150.00
Gross amount paid to the client (before Cleverbridge fees)	$126.00	$150.00

In this example, an update results in lost revenue of $24.00 per item ($150.00 - $126.00).

US Sales Taxes

When US sales tax applies, the Taxes setting should always be set to Net and IsGross should be set to False.
US sales tax on the net price is calculated at the time of billing.

Use the Value Subparameter

The CustomerPrice parameter defines the price of a single unit, not the total item price.

Calculate Total Item Price

The total item price is calculated as:

CustomerPrice × Quantity

Example

If CustomerPrice is $50 and the quantity is 3, the total item price is $150.