billing

Billing endpoint handlers.

BillingEndpoint

Bases: BaseEndpoint

Handles billing and payment-related API endpoints.

Provides methods for the credit balance and credit purchases via Stripe.

create_checkout_session(request) async

Create a Stripe checkout session for one or more credit packages.

Parameters:

Name	Type	Description	Default
request	StripeCheckoutSessionCreate	The Stripe price ids to purchase (from :meth:credit_packages — each CreditPackage.price_id) and the optional redirect URLs. success_url is required when the server has no configured public app URL; both must point to an allowed application origin when an allowlist is configured.	required

Returns:

Type	Description
StripeCheckoutSession	Stripe checkout session with a URL to complete payment.

Raises:

Type	Description
ValidationError	If the price IDs or redirect URLs are invalid.
AuthenticationError	If not authenticated.

Example

from yousleep_common.models import StripeCheckoutSessionCreate

packages = await client.billing.credit_packages()
session = await client.billing.create_checkout_session(
    StripeCheckoutSessionCreate(
        price_ids=[packages[0].price_id],
        success_url="https://app.example.com/account",
        cancel_url="https://app.example.com/account",
    )
)
print(f"Complete payment at: {session.url}")

create_portal_session(request=None) async

Open the Stripe customer portal (purchase history, invoices, receipts).

Only meaningful after at least one purchase (a Stripe customer exists) — the server responds 409 otherwise.

Parameters:

Name	Type	Description	Default
request	StripePortalSessionCreate | None	Where Stripe sends the user when they leave the portal. Omit it to use Stripe's default.	None

Returns:

Type	Description
StripePortalSession	The portal session; redirect the browser to its url.

Example

from yousleep_common.models import StripePortalSessionCreate

session = await client.billing.create_portal_session(
    StripePortalSessionCreate(return_url="https://app.example.com/account")
)
print(session.url)

credit_entries(limit=50, offset=0) async

Return a page of the org's credit ledger, newest first.

Every balance change is a ledger entry: grants, purchases, analysis charges, storage debits, what remained of a grant at its expiry and administrators' adjustments. An entry in the grants balance names its grant.

Parameters:

Name	Type	Description	Default
limit	int	Maximum entries to return (page size).	50
offset	int	Entries to skip from the newest.	0

Returns:

Type	Description
CreditLedgerPage	The page of entries plus the total entry count.

credit_packages() async

Get the purchasable credit packages (live Stripe prices).

Amounts come straight from Stripe, so what is displayed always matches what checkout charges. Pass a package's price_id to the checkout-session endpoint to purchase it.

Returns:

Type	Description
list[CreditPackage]	The packages, sorted by credits ascending.

credits() async

Return the caller's organization's credits: research grants and purchased credits.

Research analyses are paid from grants, commercial analyses and storage above the free ceiling from purchased credits. Each balance reports what is held for running analyses and what is available.

Returns:

Type	Description
OrgCredits	The organization's two balances.

Example

credits = await client.billing.credits()
print(f"Research grants available: {credits.grants.available}")