# 🧾 Billing Orchestrator
source
### SubscriptionStatus
``` python
def SubscriptionStatus(
args:VAR_POSITIONAL, kwds:VAR_KEYWORD
):
```
*Canonical subscription status values.*
Every subscription in the system maps to one of these statuses. Use
[`SubscriptionStatus.normalize()`](https://abhisheksreesaila.github.io/fh-saas/utils_billing.html#subscriptionstatus.normalize)
to map raw Stripe/legacy values.
------------------------------------------------------------------------
source
### BillingConfig
``` python
def BillingConfig(
stripe_secret_key:str='', stripe_webhook_secret:str=None, monthly_price_id:str=None, yearly_price_id:str=None,
trial_days:int=30, grace_period_days:int=3, base_url:str='http://localhost:5001', pricing_path:str='/pricing',
checkout_path:str='/checkout/{plan_type}', success_path:str='/payment-success',
cancel_path:str='/settings/payment', webhook_path:str='/stripe/webhook', portal_path:str='/billing-portal',
pricing_mode:str='public_and_post_login_pricing', allow_promotions:bool=True, is_development:bool=False
)->None:
```
*Configuration for the billing orchestrator.*
------------------------------------------------------------------------
source
### validate_billing_config
``` python
def validate_billing_config(
config:BillingConfig
)->List[str]:
```
*Validate billing configuration and return actionable error messages.*
------------------------------------------------------------------------
source
### AccessDecision
``` python
def AccessDecision(
allowed:bool, reason:SubscriptionStatus, redirect_to:Optional[str]=None
)->None:
```
*Result of a subscription access check.*
source
### PlanStore
``` python
def PlanStore(
args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):
```
*Interface for accessing pricing plan data.*
------------------------------------------------------------------------
source
### SubscriptionStore
``` python
def SubscriptionStore(
args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):
```
*Interface for subscription persistence and webhook idempotency.*
------------------------------------------------------------------------
source
### UserContextProvider
``` python
def UserContextProvider(
args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):
```
*Interface for extracting user context from HTTP requests.*
------------------------------------------------------------------------
source
### BillingUIAdapter
``` python
def BillingUIAdapter(
args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):
```
*Optional UI rendering callbacks for billing routes (headless-first).*
### Default Implementations
------------------------------------------------------------------------
source
### HostDBPlanStore
``` python
def HostDBPlanStore(
host_db
):
```
*Default PlanStore backed by HostDatabase.*
------------------------------------------------------------------------
source
### HostDBSubscriptionStore
``` python
def HostDBSubscriptionStore(
host_db
):
```
*Default SubscriptionStore backed by HostDatabase.*
------------------------------------------------------------------------
source
### RequestUserContext
``` python
def RequestUserContext(
args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):
```
*Default UserContextProvider reading from request.state.user.*
source
### init_trial_on_first_login
``` python
def init_trial_on_first_login(
tenant_id:str, user_email:str, subscription_store:SubscriptionStore, config:BillingConfig
):
```
*Create a trial subscription if the tenant has no subscription yet and
return the resolved subscription.*
------------------------------------------------------------------------
source
### resolve_subscription_access
``` python
def resolve_subscription_access(
subscription, config:BillingConfig, now:datetime=None
)->AccessDecision:
```
*Determine whether a user should be allowed access based on subscription
state. Pure function.*
------------------------------------------------------------------------
source
### resolve_checkout_return
``` python
def resolve_checkout_return(
session_id:str, tenant_id:str, subscription_store:SubscriptionStore, subscription:NoneType=None
)->SubscriptionStatus:
```
*Determine subscription state after a checkout redirect.*
source
### register_billing_routes
``` python
def register_billing_routes(
app, config:BillingConfig, plan_store:PlanStore=None, subscription_store:SubscriptionStore=None,
user_ctx:UserContextProvider=None, stripe_service:NoneType=None, ui_adapter:BillingUIAdapter=None,
host_db:NoneType=None
):
```
*Wire all billing routes onto a FastHTML app in one call.*
------------------------------------------------------------------------
source
### attach_billing_auth_hooks
``` python
def attach_billing_auth_hooks(
app, config:BillingConfig, subscription_store:SubscriptionStore=None, user_ctx:UserContextProvider=None,
host_db:NoneType=None, skip_paths:List[str]=None
):
```
*Attach first-login trial init and paywall guard as app middleware.*