Skip to main content
Version: 2.x

bursar.PostgresBillingStore

class bursar.PostgresBillingStore(database_url=None, *, tenant_id, provider_environment, pool=None, billing_payload_backend='postgres', connection_timeout_seconds=10.0, statement_timeout_ms=30000, idle_transaction_timeout_ms=30000, application_name='bursar-python', on_pool_error=None, postgres_options=None)​

Bases: BillingStore

Billing store backed by a raw Postgres connection with pooling.

Wraps all billing repositories (offer, topup, customer, subscription, event, payment, refund, invoice, dispute, config) under a single interface. All public methods delegate to the corresponding repository.

  • Parameters:
    • database_url (str | None) – Postgres connection string.
    • pool (PostgresPool | None) – Optional existing connection pool; created if not provided.
    • tenant_id (str | UUID)
    • provider_environment (ProviderEnvironment)
    • billing_payload_backend (Literal [ 'postgres' , 's3' ])
    • connection_timeout_seconds (float)
    • statement_timeout_ms (int)
    • idle_transaction_timeout_ms (int)
    • application_name (str)
    • on_pool_error (Callable [ [BursarError ] , None ] | None)
    • postgres_options (PostgresConnectionOptions | None)

property provider_environment : Literal['live', 'test', 'sandbox']​

Provider namespace used by every billing transaction.

close()​

Close all connections in the pool.

  • Return type: None

create_or_get_checkout_intent(input)​

Create or retrieve the checkout intent bound to an operation key.

  • Parameters: input (CheckoutIntentCreate)
  • Return type: CheckoutIntent

update_checkout_intent(id, update)​

Update a checkout intent’s status and optional session/URL fields.

  • Parameters:
    • id (str)
    • update (CheckoutIntentUpdate)
  • Return type: None

resolve_billing_offer(provider, product_id=None, price_id=None)​

Resolve a billing offer by provider and product/price IDs.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • product_id (str | None) – The provider product ID, or None.
    • price_id (str | None) – The provider price ID, or None.
  • Returns: BillingOfferResult if found, None otherwise.
  • Return type: BillingOfferResult | None

claim_billing_event(provider, event_id, event_type, envelope=None)​

Claim a billing event for processing (idempotent).

  • Parameters:
    • provider (str) – The billing provider identifier.
    • event_id (str) – The provider event ID.
    • event_type (str) – The event type string.
    • envelope (dict *[*str , Any ] | None)
  • Returns: BillingEventClaim with the explicit database lifecycle status.
  • Return type: BillingEventClaim

complete_billing_event(provider, event_id, claim_token)​

Mark a billing event as completed.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • event_id (str) – The provider event ID.
    • claim_token (str)
  • Return type: bool

fail_billing_event(provider, event_id, claim_token, error=None)​

Mark a billing event as failed.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • event_id (str) – The provider event ID.
    • claim_token (str)
    • error (str | None)
  • Return type: bool

upsert_billing_customer(provider, provider_customer_id, user_id, email=None)​

Insert or update a billing customer record.

  • Parameters:
    • provider (str)
    • provider_customer_id (str)
    • user_id (str)
    • email (str | None)
  • Return type: None

upsert_billing_subscription(state)​

Insert or update a billing subscription record.

  • Parameters: state (BillingSubscriptionState) – The subscription state to persist.
  • Return type: None

get_billing_customer(provider, provider_customer_id)​

Get the user ID associated with a provider customer.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • provider_customer_id (str) – The provider customer ID.
  • Returns: The user ID string if found, None otherwise.
  • Return type: str | None

get_billing_subscription(provider, provider_subscription_id)​

Get a subscription by provider and provider subscription ID.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • provider_subscription_id (str) – The provider subscription ID.
  • Returns: BillingSubscriptionState if found, None otherwise.
  • Return type: BillingSubscriptionState | None

get_user_subscription(user_id, statuses=None)​

Get the most recent subscription for a user, filtered by status.

  • Parameters:
    • user_id (str) – The user ID.
    • statuses (list *[*str ] | None) – Optional list of statuses to filter by. Defaults to (active, trialing).
  • Returns: BillingSubscriptionState if found, None otherwise.
  • Return type: BillingSubscriptionState | None

resolve_credit_topup(provider, product_id=None, price_id=None)​

Resolve a credit topup by provider and product/price IDs.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • product_id (str | None) – The provider product ID, or None.
    • price_id (str | None) – The provider price ID, or None.
  • Returns: BillingTopupResult if found, None otherwise.
  • Return type: BillingTopupResult | None

resolve_billing_offer_by_lookup(provider, lookup_key)​

Resolve a billing offer by provider and lookup key.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • lookup_key (str) – The offer lookup key.
  • Returns: BillingOfferResult if found, None otherwise.
  • Return type: BillingOfferResult | None

resolve_credit_topup_by_lookup(provider, lookup_key)​

Resolve a credit topup by provider and lookup key.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • lookup_key (str) – The topup lookup key.
  • Returns: BillingTopupResult if found, None otherwise.
  • Return type: BillingTopupResult | None

upsert_billing_payment(input)​

Insert or update a billing payment record.

  • Parameters:
    • provider – The billing provider identifier.
    • provider_payment_id – The provider payment ID.
    • provider_invoice_id – The associated invoice ID, or None.
    • user_id – The user ID, or None.
    • amount_minor – The payment amount in minor currency units.
    • tax_minor – The tax amount in minor currency units, or None.
    • currency – The ISO 4217 currency code (default “USD”).
    • purpose – The payment purpose (default “unknown”).
    • status – The payment status (default “succeeded”).
    • provider_updated_at – Optional provider timestamp.
    • metadata – Optional structured metadata dict.
    • input (BillingPaymentUpsert)
  • Return type: str

upsert_billing_refund(input)​

Insert or update a billing refund record.

  • Parameters:
    • provider – The billing provider identifier.
    • provider_refund_id – The provider refund ID.
    • provider_payment_id – The associated payment ID, or None.
    • user_id – The user ID, or None.
    • amount_minor – The refund amount in minor currency units.
    • currency – The ISO 4217 currency code (default “USD”).
    • reason – The refund reason, or None.
    • status – The refund status (default “pending”).
    • provider_updated_at – Optional provider timestamp.
    • metadata – Optional structured metadata dict.
    • input (BillingRefundUpsert)
  • Return type: str

upsert_billing_invoice(input)​

Insert or update a billing invoice record.

  • Parameters:
    • provider – The billing provider identifier.
    • provider_invoice_id – The provider invoice ID.
    • provider_subscription_id – The associated subscription ID, or None.
    • user_id – The user ID, or None.
    • status – The invoice status, or None.
    • amount_paid_minor – Amount paid in minor currency units, or None.
    • amount_due_minor – Amount due in minor currency units, or None.
    • currency – The ISO 4217 currency code (default “USD”).
    • period_start – The billing period start, or None.
    • period_end – The billing period end, or None.
    • metadata – Optional structured metadata dict.
    • input (BillingInvoiceUpsert)
  • Return type: None

upsert_billing_dispute(input)​

Insert or update a billing dispute record.

  • Parameters:
    • provider – The billing provider identifier.
    • provider_dispute_id – The provider dispute ID.
    • provider_payment_id – The associated payment ID, or None.
    • user_id – The user ID, or None.
    • status – The dispute status (default “needs_response”).
    • reason – The dispute reason, or None.
    • metadata – Optional structured metadata dict.
    • input (BillingDisputeUpsert)
  • Return type: None

get_billing_payment(provider, provider_payment_id)​

Get persisted payment state for refund processing.

  • Parameters:
    • provider (str) – The billing provider identifier.
    • provider_payment_id (str) – The provider payment ID.
  • Returns: Persisted payment state if found, None otherwise.
  • Return type: BillingPaymentRecord | None

get_user_subscriptions(user_id)​

Get all subscriptions for a user.

  • Parameters: user_id (str) – The user ID.
  • Returns: List of BillingSubscriptionState (may be empty).
  • Return type: list[BillingSubscriptionState]

get_billing_preferences(user_id)​

Get billing preferences for a user.

  • Parameters: user_id (str) – The user ID.
  • Returns: BillingPreferences if found, None otherwise.
  • Return type: BillingPreferences | None

upsert_billing_preferences(prefs)​

Insert or update billing preferences for a user.

  • Parameters: prefs (BillingPreferences) – The billing preferences to persist.
  • Return type: None

get_billing_customer_by_user_id(user_id, provider=None)​

Reverse lookup: find a customer record by user ID.

  • Parameters:
    • user_id (str) – The user ID.
    • provider (str | None) – Optional provider filter.
  • Returns: BillingCustomerRecord if found, None otherwise.
  • Return type: BillingCustomerRecord | None