Pricing API 

Parameters:

previous_plan (Dict[str, Any])
new_plan (Dict[str, Any])
days_used (int)
days_in_period (int)

abstractmethod async get_billing_items(**kwargs)[source]

Get items for a bill/invoice.

Return type:: List[Dict[str, Any]]

abstractmethod async validate_plan_change(current_plan, new_plan)[source]

Validate if a plan change is allowed.

Return type:

Parameters:

current_plan (Dict[str, Any])
new_plan (Dict[str, Any])

round_price(amount)[source]

Round the price according to configuration.

Return type:: float
Parameters:: amount (float)

apply_tax(amount, tax_rate=None)[source]

Apply tax to the amount.

Return type:

Parameters:

amount (float)
tax_rate (float | None)

calculate_tax_amount(amount, tax_rate=None)[source]

Calculate the tax amount.

Return type:

Parameters:

amount (float)
tax_rate (float | None)

Subscription Pricing

class fastapi_payments.pricing.subscription.SubscriptionPricing(config)[source]

Pricing strategy for subscription-based pricing.

Methods:

`calculate_price`(base_amount[, quantity, ...])	Calculate the final price for a subscription.
`calculate_proration`(previous_plan, new_plan, ...)	Calculate the prorated amount when changing plans.
`get_billing_items`(plan_id, plan_name, ...[, ...])	Get billing items for a subscription.
`validate_plan_change`(current_plan, new_plan)	Validate if a subscription plan change is allowed.

Parameters:: config (PricingConfig)

async calculate_price(base_amount, quantity=1, discount_percentage=None, discount_amount=None, tax_rate=None, **kwargs)[source]

Calculate the final price for a subscription.

Parameters:

base_amount (float) – Base price of the subscription
quantity (int) – Number of units/seats
discount_percentage (Optional[float]) – Optional percentage discount (0.0 to 1.0)
discount_amount (Optional[float]) – Optional fixed discount amount
tax_rate (Optional[float]) – Optional tax rate override

Return type:

Returns:

Final calculated price

async calculate_proration(previous_plan, new_plan, days_used, days_in_period)[source]

Calculate the prorated amount when changing plans.

Parameters:

previous_plan (Dict[str, Any]) – Original plan details
new_plan (Dict[str, Any]) – New plan details
days_used (int) – Number of days used in current period
days_in_period (int) – Total days in billing period

Return type:

Returns:

Prorated amount for the billing adjustment

async get_billing_items(plan_id, plan_name, plan_amount, quantity=1, period_start=None, period_end=None, discount_percentage=None, discount_amount=None, tax_rate=None, **kwargs)[source]

Get billing items for a subscription.

Return type:

List[Dict[str, Any]]

Returns:

List of billing items including base subscription, discounts, and taxes

Parameters:

plan_id (str)
plan_name (str)
plan_amount (float)
quantity (int)
period_start (datetime)
period_end (datetime)
discount_percentage (float | None)
discount_amount (float | None)
tax_rate (float | None)

async validate_plan_change(current_plan, new_plan)[source]

Validate if a subscription plan change is allowed.

Parameters:

current_plan (Dict[str, Any]) – Current plan details
new_plan (Dict[str, Any]) – New plan details

Return type:

Returns:

True if the plan change is allowed, False otherwise

Usage-Based Pricing

class fastapi_payments.pricing.usage_based.UsageBasedPricing(price_per_unit, minimum_charge=0.0, maximum_charge=None, tax_rate=0.0)[source]

Usage-based pricing strategy that charges based on consumption.

Methods:

`__init__`(price_per_unit[, minimum_charge, ...])	Initialize the usage-based pricing strategy.
`calculate_price`([usage, tax_rate])	Calculate price using usage-based model.
`get_billing_items`([usage])	Get itemized billing details.
`calculate_proration`(days_used, days_in_period)	Calculate prorated amount.
`validate_plan_change`(current_plan, new_plan)	Validate if a plan change is allowed.

__init__(price_per_unit, minimum_charge=0.0, maximum_charge=None, tax_rate=0.0)[source]

Initialize the usage-based pricing strategy.

Parameters:

price_per_unit – Price per unit of usage
minimum_charge – Minimum charge regardless of usage
maximum_charge – Maximum charge cap (optional)
tax_rate – Tax rate

calculate_price(usage=0, tax_rate=None)[source]

Calculate price using usage-based model.

Parameters:

usage – Usage units
tax_rate – Override default tax rate (optional)

Return type:

Returns:

Calculated total price

get_billing_items(usage=0)[source]

Get itemized billing details.

Parameters:: usage – Usage units
Return type:: List[Dict[str, Any]]
Returns:: List of billing items

calculate_proration(days_used, days_in_period, usage=0)[source]

Calculate prorated amount.

Parameters:

days_used – Days used in period
days_in_period – Total days in period
usage – Usage units

Return type:

Returns:

Prorated price

validate_plan_change(current_plan, new_plan)[source]

Validate if a plan change is allowed.

Parameters:

current_plan (Dict[str, Any]) – Current plan details
new_plan (Dict[str, Any]) – New plan details to switch to

Return type:

Returns:

True if the plan change is allowed, False otherwise

Tiered Pricing

class fastapi_payments.pricing.tiered.TieredPricing(tiers, tax_rate=0.0)[source]

Tiered pricing strategy with different rates for different usage tiers.

Methods:

`__init__`(tiers[, tax_rate])	Initialize the tiered pricing strategy.
`calculate_price`([usage, tax_rate])	Calculate price using tiered model.
`get_billing_items`([usage])	Get itemized billing details.
`calculate_proration`(days_used, days_in_period)	Calculate prorated amount.
`validate_plan_change`(current_plan, new_plan)	Validate if a plan change is allowed.

__init__(tiers, tax_rate=0.0)[source]: Initialize the tiered pricing strategy.

calculate_price(usage=0, tax_rate=None)[source]

Calculate price using tiered model.

Return type:: float

get_billing_items(usage=0)[source]

Get itemized billing details.

Return type:: List[Dict[str, Any]]

calculate_proration(days_used, days_in_period, usage=0)[source]

Calculate prorated amount.

Parameters:

days_used – Days used in period
days_in_period – Total days in period
usage – Usage units

Return type:

Returns:

Prorated price

validate_plan_change(current_plan, new_plan)[source]

Validate if a plan change is allowed.

Parameters:

current_plan (Dict[str, Any]) – Current plan details
new_plan (Dict[str, Any]) – New plan details to switch to

Return type:

Returns:

True if the plan change is allowed, False otherwise

Per-User Pricing

class fastapi_payments.pricing.per_user.PerUserPricing(base_price, price_per_user=0.0, minimum_users=1, tax_rate=0.0)[source]

Per-user pricing strategy that charges based on number of users/seats.

Methods:

`__init__`(base_price[, price_per_user, ...])	Initialize the per-user pricing strategy.
`calculate_price`([base_amount, num_users, ...])	Calculate price using per-user model (test implementation).
`get_billing_items`([plan_id, plan_name, ...])	Get itemized billing details (test implementation).
`calculate_proration`(previous_plan, new_plan, ...)	Calculate proration for plan changes (test implementation).
`validate_plan_change`(current_plan, new_plan)	Validate if a plan change is allowed.

__init__(base_price, price_per_user=0.0, minimum_users=1, tax_rate=0.0)[source]

Initialize the per-user pricing strategy.

Parameters:

base_price – Base price (platform fee)
price_per_user – Price per user/seat
minimum_users – Minimum number of users to charge for
tax_rate – Tax rate

async calculate_price(base_amount=0.0, num_users=1, minimum_users=None, discount_percentage=0.0, discount_tiers=None, tax_rate=None)[source]

Calculate price using per-user model (test implementation).

Parameters:

base_amount – Base amount per user
num_users – Number of users/seats
minimum_users – Override minimum users (optional)
discount_percentage – Flat discount percentage (optional)
discount_tiers – Tiered discounts based on user count (optional)
tax_rate – Override default tax rate (optional)

Returns:

Calculated total price

async get_billing_items(plan_id=None, plan_name=None, base_amount=0.0, num_users=1, period_start=None, period_end=None, discount_tiers=None)[source]

Get itemized billing details (test implementation).

Parameters:

plan_id – Plan ID
plan_name – Plan name
base_amount – Base amount per user
num_users – Number of users/seats
period_start – Subscription period start
period_end – Subscription period end
discount_tiers – Tiered discounts based on user count

Returns:

List of billing items

async calculate_proration(previous_plan, new_plan, days_used, days_in_period)[source]

Calculate proration for plan changes (test implementation).

Parameters:

previous_plan – Previous plan details
new_plan – New plan details
days_used – Days used in current period
days_in_period – Total days in period

Returns:

Proration amount

validate_plan_change(current_plan, new_plan)[source]

Validate if a plan change is allowed.

Parameters:

current_plan (Dict[str, Any]) – Current plan details
new_plan (Dict[str, Any]) – New plan details to switch to

Return type:

Returns:

True if the plan change is allowed, False otherwise

Freemium Pricing

class fastapi_payments.pricing.freemium.FreemiumPricing(base_price=0.0, free_tier_limit=0, paid_tier_price=0.0, tax_rate=0.0)[source]

Freemium pricing strategy with free tier and paid upgrades.

Methods:

`__init__`([base_price, free_tier_limit, ...])	Initialize the freemium pricing strategy.
`calculate_price`([usage, tax_rate])	Calculate price using freemium model.
`get_billing_items`([usage])	Get itemized billing details.
`calculate_proration`(days_used, days_in_period)	Calculate prorated amount for paid tier.
`validate_plan_change`(current_plan, new_plan)	Validate if a plan change is allowed.

__init__(base_price=0.0, free_tier_limit=0, paid_tier_price=0.0, tax_rate=0.0)[source]

Initialize the freemium pricing strategy.

Parameters:

base_price – Base price (usually 0 for freemium)
free_tier_limit – Usage limit for free tier
paid_tier_price – Price for paid tier
tax_rate – Tax rate

calculate_price(usage=0, tax_rate=None)[source]

Calculate price using freemium model.

Parameters:

usage – Usage units
tax_rate – Override default tax rate (optional)

Return type:

Returns:

Calculated total price (0 if within free tier)

get_billing_items(usage=0)[source]

Get itemized billing details.

Parameters:: usage – Usage units
Returns:: List of billing items

calculate_proration(days_used, days_in_period, usage=0)[source]

Calculate prorated amount for paid tier.

Parameters:

days_used – Days used in period
days_in_period – Total days in period
usage – Current usage level

Return type:

Returns:

Prorated price (0 if in free tier)

validate_plan_change(current_plan, new_plan)[source]

Validate if a plan change is allowed.

Parameters:

current_plan (Dict[str, Any]) – Current plan details
new_plan (Dict[str, Any]) – New plan details to switch to

Return type:

Returns:

True if the plan change is allowed, False otherwise

Dynamic Pricing

class fastapi_payments.pricing.dynamic.DynamicPricing(base_price, default_multiplier=1.0, tax_rate=0.0)[source]

Dynamic pricing strategy based on variable multipliers.

Methods:

`__init__`(base_price[, default_multiplier, ...])	Initialize the dynamic pricing strategy.
`calculate_price`([custom_multiplier, tax_rate])	Calculate price using dynamic pricing.
`get_billing_items`([custom_multiplier])	Get itemized billing details.
`calculate_proration`(days_used, days_in_period)	Calculate prorated price amount.
`validate_plan_change`(current_plan, new_plan)	Validate if a plan change is allowed.

__init__(base_price, default_multiplier=1.0, tax_rate=0.0)[source]

Initialize the dynamic pricing strategy.

Parameters:

base_price – Base price
default_multiplier – Default price multiplier to apply
tax_rate – Tax rate

calculate_price(custom_multiplier=None, tax_rate=None)[source]

Calculate price using dynamic pricing.

Parameters:

custom_multiplier – Override default multiplier (optional)
tax_rate – Override default tax rate (optional)

Returns:

Calculated total price

get_billing_items(custom_multiplier=None)[source]

Get itemized billing details.

Parameters:: custom_multiplier – Override default multiplier (optional)
Returns:: List of billing items

calculate_proration(days_used, days_in_period, quantity=1)[source]

Calculate prorated price amount.

Parameters:

days_used (int) – Days used in period
days_in_period (int) – Total days in period
quantity (int) – Quantity (not typically used in dynamic pricing)

Return type:

Returns:

Prorated price amount

validate_plan_change(current_plan, new_plan)[source]

Validate if a plan change is allowed.

Parameters:

current_plan (Dict[str, Any]) – Current plan details
new_plan (Dict[str, Any]) – New plan details to switch to

Return type:

Returns:

True if the plan change is allowed, False otherwise

Hybrid Pricing

class fastapi_payments.pricing.hybrid.HybridPricing(base_price, usage_rate=0.0, tax_rate=0.0)[source]

Hybrid pricing strategy combining subscription and usage-based billing.

Methods:

`__init__`(base_price[, usage_rate, tax_rate])	Initialize the hybrid pricing strategy.
`calculate_price`([quantity, usage, tax_rate])	Calculate price using hybrid pricing model.
`get_billing_items`([quantity, usage])	Get itemized billing details.
`calculate_proration`(days_used, days_in_period)	Calculate prorated subscription amount.
`validate_plan_change`(current_plan, new_plan)	Validate if a plan change is allowed.

__init__(base_price, usage_rate=0.0, tax_rate=0.0)[source]

Initialize the hybrid pricing strategy.

Parameters:

base_price – Base subscription price
usage_rate – Price per usage unit
tax_rate – Tax rate

calculate_price(quantity=1, usage=0, tax_rate=None)[source]

Calculate price using hybrid pricing model.

Parameters:

quantity – Subscription quantity
usage – Usage units
tax_rate – Override default tax rate (optional)

Returns:

Calculated total price

get_billing_items(quantity=1, usage=0)[source]

Get itemized billing details.

Parameters:

quantity – Subscription quantity
usage – Usage units

Returns:

List of billing items

calculate_proration(days_used, days_in_period, quantity=1)[source]

Calculate prorated subscription amount.

Parameters:

days_used – Days used in period
days_in_period – Total days in period
quantity – Subscription quantity

Returns:

Prorated subscription price

validate_plan_change(current_plan, new_plan)[source]

Validate if a plan change is allowed.

Parameters:

current_plan (Dict[str, Any]) – Current plan details
new_plan (Dict[str, Any]) – New plan details to switch to

Return type: