Billing and subscriptions

List plans

plans() accepts either pk_ or sk_ credentials.

plans = nozle.plans()

for plan in plans:
    print(
        plan["code"],
        plan["amount_cents"],
        plan["amount_currency"],
        plan["interval"],
    )

Each Plan is a typed dictionary containing code, name, amount_cents, amount_currency, and interval.

Create checkout

result = nozle.checkout(
    "workspace_123",
    "pro_monthly",
    return_url="https://app.example.com/settings/billing",
)

checkout() requires sk_ and returns one of three typed result variants:

StripeCheckoutResult with a hosted url or embedded client_secret;
CompletedCheckoutResult; or
ScheduledCheckoutResult.

if result["type"] == "stripe":
    if "url" in result:
        redirect_to = result["url"]
    else:
        client_secret = result.get("client_secret") or result.get("clientSecret")
elif result["type"] == "completed":
    refresh_billing_state()
else:
    show_scheduled_change(result["status"])

Validate the exact HTTPS return origin before passing a browser-provided URL to this method.

Deprecated `success_url`

success_url= remains a deprecated alias for return_url=. The SDK emits DeprecationWarning, sends only return_url, and rejects conflicting values with NozleValidationError.

Stripe webhooks remain authoritative. Checkout return values and browser redirects are interface signals, not proof that a paid subscription is active.

Direct subscription

subscription = nozle.subscribe("workspace_123", "free")

print(subscription["subscription_id"])
print(subscription["status"])

Use checkout for payment-gated changes. Use direct subscription only when the configured flow does not require interactive payment.

Cancellation

result = nozle.cancel_subscription(
    "workspace_123",
    "subscription_123",
    policy="end_of_period",
)

The policy defaults to end_of_period and also accepts immediate.

Entity subscriptions

nozle.entity_subscriptions.ensure("workspace_123", "user_42")

checkout = nozle.entity_subscriptions.checkout(
    "workspace_123",
    "user_42",
    plan_code="pro_monthly",
    billing_time="anniversary",
    return_url="https://app.example.com/settings/billing",
    idempotency_key="checkout-user-42-pro-v1",
)

Change or cancel only that Entity:

nozle.entity_subscriptions.change_plan(
    "workspace_123",
    "user_42",
    plan_code="max_annual",
    return_url="https://app.example.com/settings/billing",
    idempotency_key="change-user-42-max-v1",
)

nozle.entity_subscriptions.cancel(
    "workspace_123",
    "user_42",
    timing="end_of_period",
    idempotency_key="cancel-user-42-v1",
)

Every method requires an sk_ key. See Entity Subscriptions for lifecycle and payment behavior. The Python SDK currently exposes single-Entity checkout and plan changes. For a mixed seat-pool purchase, call the bulk Entity checkout endpoint from your trusted backend. Do not loop over entity_subscriptions.checkout(), because each call creates an independent checkout instead of one combined invoice.

Settlement transitions

params = {
    "customer_id": "workspace_123",
    "subscription_id": "subscription_123",
    "operation": "downgrade",
    "timing": "end_of_period",
    "target_plan_code": "growth_monthly",
    "credit_action": "none",
}

preview = nozle.preview_subscription_transition(params)

transition = nozle.apply_subscription_transition(
    params,
    idempotency_key="transition-subscription-123-growth-v1",
)

Apply requires an idempotency key up to 255 UTF-8 bytes. See Subscriptions for settlement options and validation rules.

Upsert the customer first

customer = nozle.customers.upsert(
    "workspace_123",
    name="Acme Workspace",
    email="billing@example.com",
)

See Customers and Entities for lifecycle details.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Billing and subscriptions

List plans

Create checkout

Deprecated `success_url`

Direct subscription

Cancellation

Entity subscriptions

Settlement transitions

Upsert the customer first

​List plans

​Create checkout

​Deprecated success_url

​Direct subscription

​Cancellation

​Entity subscriptions

​Settlement transitions

​Upsert the customer first

List plans

Create checkout

Deprecated `success_url`

Direct subscription

Cancellation

Entity subscriptions

Settlement transitions

Upsert the customer first