Billing and subscriptions

List plans

plans() accepts either pk_ or sk_ credentials.

from nozle import Nozle

nozle = Nozle()  # reads NOZLE_SECRET_KEY

plans = nozle.plans()

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

The Plan typed dictionary declares code, name, amount_cents, amount_currency, and interval. At runtime each item is the full plan dictionary from the API, including charges, entitlements, taxes and credit_grant_rules, and the list includes trial, pay-in-arrears and pending-deletion plans. See the public plan catalog. With a pk_ key, all of it is readable by anyone who has the key.

Create checkout

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

checkout() requires an sk_ key and returns a typed dictionary. Handle each type explicitly:

`type`	Fields	Handling
`stripe`	`client_secret`/`clientSecret` (`cs_...`), `invoice_id`, `amount_cents`, `currency`	Mount Stripe embedded Checkout with the client secret. Plan and invoice checkout never return a Stripe `url`; only credit top-ups return a Stripe-hosted `payment_url`. See the Stripe flow.
`razorpay`	`checkout_id`, `key_id`, `order_id`, `amount_cents`, `currency`, `expires_at`, `invoice_id`; with a mandate also `customer_id`, `recurring: True`, `mandate_max_amount_cents`	Open Razorpay Checkout, then verify the genuine callback through your backend. See the Razorpay flow.
`hosted`	`payment_url`	Not returned by `checkout()` or `checkout_invoice()`. The type still exists for a Razorpay payment link: navigate to `payment_url`. Invoice payment URLs and credit top-ups return a `payment_url` without a `type`.
`processing`	`checkout_id`, `status`	Razorpay: the order is not ready or has expired. Stripe: a replayed quoted upgrade whose webhook is still pending. Recover with `checkout_status(checkout_id)`. `status` is an internal operation status.
`completed`	`status: "succeeded"`, `subscription_id`, `plan_code`, `invoice_id` (may be `None`), `amount_cents`, `currency`, `payment_source` (`credits` or `none`)	Refresh authoritative subscription state.
`scheduled`	`status: "pending"`, `subscription_id`, `plan_code`, `transition_direction`, `transition_policy`, `effective_at`	Display the pending change and its effective date.

A paid upgrade returns plan_upgrade_intent_id instead of invoice_id on stripe and razorpay results. On scheduled, subscription_id is the pending subscription. pending_subscription_id was removed from the result type in 0.10.0 because the API never returns it; earlier versions declared it. Do not handle all non-Stripe responses as scheduled changes. See the React checkout components for the browser integration. Validate the exact HTTPS return origin before passing a browser-provided URL to this method.

Checkout errors

Status	`code`	Cause
400	`invalid_return_url`	The `return_url` origin is not allowed. Checked before anything else.
404	`plan_not_found`, `customer_not_found`	Unknown plan or customer.
409	`subscription_selection_required`	The customer has several active subscriptions and no `subscription_id` was given.
422	`checkout_not_required`	The plan needs no up-front payment (free, trial, or pay-in-arrears) and the customer has no subscription. Use `subscribe()` instead.
422	`payment_provider_required`	No payment provider is connected.
422	`plan_already_active`	The customer is already on that plan.
409	`subscription_checkout_in_progress`	A payment for the customer’s new-subscription checkout on a different plan is still processing, or it was paid. An abandoned checkout is replaced instead, and the same plan reopens it.

The SDK raises NozleValidationError before any request when register_mandate is not a bool, or when quote_id is given without subscription_id. See Create checkout for the HTTP contract.

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.

Nozle payment fulfillment is authoritative. Browser callbacks and redirects do not prove activation; Razorpay upgrades require capture and Stripe requires backend settlement.

Manage a payment method

page = nozle.manage_payment_method(
    "workspace_123",
    "https://app.example.com/settings/billing",
)

redirect(page["url"])  # Stripe Billing Portal

Stripe only. Requires an sk_ key. A pk_ key is refused with 403 (no error code, only a message). Nozle stores no card data: the customer changes their payment method in the Stripe Billing Portal. Razorpay customers pay each invoice through a Razorpay payment link, so for them the call fails with 422 razorpay_pays_by_link. See Manage Payment Method for the HTTP contract and error codes.

Direct subscription

nozle.customers.upsert("workspace_123", name="Acme Workspace")
subscription = nozle.subscribe("workspace_123", "free")

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

The customer must already exist, so call customers.upsert() first. An unknown customer returns 404 customer_not_found and nothing is created. Calling subscribe() again for the same customer and plan returns the same subscription. subscribe() accepts a paid plan without collecting payment. Use checkout for payment-gated changes. Use direct subscription only when the configured flow does not require interactive payment.

subscribe() to another plan adds a second active subscription. It does not replace the first, and plan credit grants are granted again. To move a customer, call checkout() with subscription_id (needs a transition policy), or cancel and then subscribe. Pass the new subscription ID to track(): cached clients keep the old ID.

Cancellation

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

The policy defaults to end_of_period and also accepts immediate.

Subscription self-service

The following subscription-management methods are available from nozle-sdk 0.10.0. The matching hosted endpoints are available; see the Python merchant example for a complete integration.

These methods power the React billing portal. Derive customer_id from the authenticated application user and validate the selected external subscription_id. Do not substitute the Core internal UUID for that external identifier.

Changing an existing subscription’s plan needs a transition policy for that source and target plan pair. Without one, preview, checkout, and transitions return 422 plan_transition_policy_required. Exception: from a $0 plan to a paid plan, the organization’s free-to-paid default applies without a pair policy.

Load eligible plans and preview a quote

options = nozle.subscription_options(customer_id, subscription_id)
quote = nozle.preview_subscription_change(customer_id, subscription_id, target_plan_code)

SubscriptionOptions is a typed dictionary with subscription, pending_change, eligible_plans, and optional checkout. Plans contain code, name, amount_cents, currency, and interval; eligible plans add direction and timing. A pending change has its own internal id and effective_at. SubscriptionChangePreview contains quote_id, transition_direction, timing, currency, credit_amount_cents, debit_amount_cents, net_amount_cents, amount_due_now_cents, amount_due_at_effective_cents, effective_at, and renewal_at. The API also returns transition_policy, billing_anchor, proration_behavior, and credit_action, which the type omits. Show these exact amounts and dates before confirmation. Minor-unit amounts may be integers or strings; preserve their precision. Eligibility comes from configured transition policies, not a client-side price comparison.

Confirm a paid upgrade

After the customer confirms, use the saved quote and a stable action key:

checkout = nozle.checkout(
    customer_id,
    target_plan_code,
    return_url=return_url,
    subscription_id=subscription_id,
    quote_id=quote["quote_id"],
    idempotency_key=confirmed_action_key,
)

quote_id requires subscription_id. Quotes expire after five minutes or become invalid when their bound state changes. On HTTP 409, request a new preview and confirmation. For an uncertain response, retry the same confirmed request and key; an accepted request can replay after quote expiry. A $0 to $0 immediate upgrade returns completed with payment_source: "credits" and creates a $0 invoice. An upgrade checkout to a pay-in-arrears plan returns 422 plan_upgrade_invoice_missing.

Schedule or withdraw a downgrade

For a confirmed quote with transition_direction == "downgrade":

scheduled = nozle.apply_subscription_transition(
    {
        "customer_id": customer_id,
        "subscription_id": subscription_id,
        "operation": "downgrade",
        "target_plan_code": target_plan_code,
        "timing": "end_of_period",
        "billing_anchor": "keep_anchor",
        "quote_id": quote["quote_id"],
    },
    idempotency_key=confirmed_action_key,
)

Reload options to display the pending change separately from the current plan. Retain the exact pending_change["id"] shown in the customer’s withdrawal confirmation:

withdrawn = nozle.withdraw_pending_subscription_change(
    customer_id,
    subscription_id,
    confirmed_pending_subscription_id,
    idempotency_key=withdrawal_action_key,
)

The result is {"subscription": {"id", "external_id", "plan_code", "status"}, "withdrawn_pending_subscription_id", "replayed"}. The same key returns the same body with replayed: True. Withdrawal preserves the active plan. A new scheduled change while a change is pending replaces it with a new pending ID. A paid upgrade checkout is refused with 409 subscription_change_pending while a downgrade or cancellation is scheduled: withdraw the downgrade, or keep the subscription, first. Scheduling a change or cancelling at period end cancels an open upgrade checkout. Withdrawing the replaced ID returns 409 pending_subscription_changed. An unknown ID returns 404 pending_subscription_not_found.

Cancel at period end and Keep

Preview through the existing transition method:

cancellation = nozle.preview_subscription_transition({
    "customer_id": customer_id,
    "subscription_id": subscription_id,
    "operation": "cancel",
    "timing": "end_of_period",
})

After displaying and confirming the ending date, forward the exact timestamp:

nozle.apply_subscription_transition(
    {
        "customer_id": customer_id,
        "subscription_id": subscription_id,
        "operation": "cancel",
        "timing": "end_of_period",
        "expected_effective_at": cancellation["subscription_transition"]["effective_at"],
    },
    idempotency_key=cancellation_action_key,
)

Keep uses uncancel with a separate confirmed action key and no settlement overrides:

nozle.apply_subscription_transition(
    {"customer_id": customer_id, "subscription_id": subscription_id, "operation": "uncancel"},
    idempotency_key=keep_action_key,
)

Keep is available only before the ending is due. Cancellation clears a pending downgrade; Keep does not recreate it. Preserve the preview’s full timestamp, including timezone and fractional seconds.

Scope payment recovery and verification

payment = nozle.checkout_status(
    checkout_id, customer_id=customer_id, subscription_id=subscription_id,
)
verified = nozle.verify_checkout(
    checkout_id,
    razorpay_verification,
    customer_id=customer_id,
    subscription_id=subscription_id,
)

Forward the genuine Razorpay callback’s razorpay_order_id, razorpay_payment_id, and razorpay_signature; a missing field raises before any request. The optional scope fields must be supplied together. Existing calls without them remain compatible; include both for customer-specific recovery. An unknown checkout ID returns 404 checkout_session_not_found. Status distinguishes awaiting_payment, processing, succeeded, failed, expired, and needs_review, with a separate fulfillment_status. Reload the selected subscription before reporting activation. Keep the existing checkout for recoverable retries and use your support route for uncertain payments before another collection. The merchant example maps these dictionaries to React’s camelCase action types and persists retry context. Replace its demo login/file store with your application’s authentication and transactional storage for production workers. See the HTTP contract.

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",
    credit_action="none",
    idempotency_key="cancel-user-42-v1",
)

Every method requires an sk_ key. See Entity Subscriptions for lifecycle and payment behavior.

billing_time accepts only calendar or anniversary.
Single Entity checkout also accepts free, trial, and pay-in-arrears plans. It returns completed with payment_source: "none".
change_plan() needs a transition policy for the plan pair. From 0.13.0 it accepts billing_time; earlier versions take none. It returns scheduled or completed, plus external_entity_id and external_subscription_id.
cancel() requires idempotency_key. On a pay-in-arrears plan without credit_action it returns 422 with credit_action: not_supported_for_pay_in_arrears.
remove() on an Entity with billing history returns 403 entity_subscription_has_billing_history.

Buy several Entity plans together

checkout_many() buys plans for several Entities with one payment. Do not loop over entity_subscriptions.checkout(): each call creates an independent checkout instead of one combined invoice.

batch = nozle.entity_subscriptions.checkout_many(
    "workspace_123",
    items=[
        {"external_entity_id": "user_42", "plan_code": "pro_monthly"},
        {"external_entity_id": "user_43", "plan_code": "max_monthly"},
    ],
    billing_time="anniversary",
    return_url="https://app.example.com/settings/billing",
    idempotency_key="seats-workspace-123-v1",
)

The result contains id, type (stripe, razorpay, processing, or completed), status (pending, open, completed, failed, or expired), client_secret, invoice_id, amount_cents, currency, replayed, expires_at, and items with external_entity_id, external_subscription_id, plan_code, and subscription_status. Razorpay results add the Razorpay fields.

Send 1 to 100 unique external_entity_id values. The SDK checks this before any request.
idempotency_key is required, up to 255 bytes, and sent as the Idempotency-Key header. The same key and request returns replayed: True and reuses the open session. Replaying a failed or expired batch returns checkout_not_available.
The checkout expires after 23 hours.
Every plan must require up-front payment: pay in advance with an amount above 0 and no trial, or pay-in-advance fixed charges. Otherwise the whole batch fails with 422 validation_errors and error_details["items"] == ["paid_plan_required"]. Other item errors are mixed_currencies and mixed_intervals.
An untrusted return_url returns 422 with return_url: invalid_or_untrusted.
With no payment provider connected, the call returns 422 payment_provider_required, as single checkout does.

See bulk Entity checkout.

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. These methods use the timing you pass even when the pair’s transition policy says otherwise; checkout always follows the policy. A downgrade on a pair whose policy direction is upgrade returns 422 target_plan_is_not_a_downgrade. 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.

Read usage

From 0.13.0.

current = nozle.current_usage("cus_123")              # this billing period
past = nozle.past_usage("cus_123", periods=6)         # newest first

Each period is a CustomerUsage with from_datetime, to_datetime, currency, amount_cents, total_amount_cents and charges_usage (units and amount per charge and feature). Pass subscription_id to read a specific subscription. Without a subscription ID, the customer’s one active subscription is used, and a customer with none or several gets an error.

Invoices

From 0.13.0.

page = nozle.invoices.list("cus_123", status="finalized", page=1)    # {"invoices", "meta"}
invoice = nozle.invoices.get(page["invoices"][0]["nozle_id"])
pdf = nozle.invoices.download_url(invoice["nozle_id"])               # str or None

invoices.list returns the newest invoices first and takes these keyword filters:

Argument	Description
`status`	`draft`, `finalized`, `voided`, `failed` or `pending`.
`payment_status`	`pending`, `succeeded` or `failed`.
`payment_overdue`	`True` keeps only unpaid invoices past their due date; `False` keeps the others.
`issuing_date_from`, `issuing_date_to`	Inclusive issuing dates, `YYYY-MM-DD`.
`page`, `per_page`	Page number and page size.

overdue = nozle.invoices.list("cus_123", payment_overdue=True)

Pay an open invoice with checkout_invoice. A PDF is generated the first time it is asked for, so the download call returns no URL until it exists; ask again a few seconds later, or wait for the invoice.generated webhook.

Alerts

From 0.13.0.

nozle.alerts.create(
    "feature_current_usage_units",
    "api_calls_80",
    [{"value": 40000}, {"value": 10000, "recurring": True}],
    feature_code="api_calls",
    subscription_id="sub_123",
)
alerts = nozle.alerts.list(subscription_id="sub_123")["alerts"]
nozle.alerts.update("api_calls_80", name="API calls at 80%", subscription_id="sub_123")
nozle.alerts.delete("api_calls_80", subscription_id="sub_123")

# Balance alerts belong to a wallet:
nozle.alerts.create(
    "wallet_credits_balance", "low_credits", [{"value": 100}],
    customer_id="cus_123", wallet_code="main",
)

Usage alert types are current_usage_amount, feature_current_usage_amount and feature_current_usage_units (the feature_* ones need a feature code). Wallet alert types are wallet_balance_amount, wallet_credits_balance, wallet_ongoing_balance_amount and wallet_credits_ongoing_balance. Threshold values are cents, units or credits by type, and at most one threshold is recurring. Nozle sends the alert.triggered webhook when a threshold is crossed; verify it before acting.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Billing and subscriptions

List plans

Create checkout

Checkout errors

Deprecated `success_url`

Manage a payment method

Direct subscription

Cancellation

Subscription self-service

Load eligible plans and preview a quote

Confirm a paid upgrade

Schedule or withdraw a downgrade

Cancel at period end and Keep

Scope payment recovery and verification

Entity subscriptions

Buy several Entity plans together

Settlement transitions

Upsert the customer first

Read usage

Invoices

Alerts

​List plans

​Create checkout

​Checkout errors

​Deprecated success_url

​Manage a payment method

​Direct subscription

​Cancellation

​Subscription self-service

​Load eligible plans and preview a quote

​Confirm a paid upgrade

​Schedule or withdraw a downgrade

​Cancel at period end and Keep

​Scope payment recovery and verification

​Entity subscriptions

​Buy several Entity plans together

​Settlement transitions

​Upsert the customer first

​Read usage

​Invoices

​Alerts

List plans

Create checkout

Checkout errors

Deprecated `success_url`

Manage a payment method

Direct subscription

Cancellation

Subscription self-service

Load eligible plans and preview a quote

Confirm a paid upgrade

Schedule or withdraw a downgrade

Cancel at period end and Keep

Scope payment recovery and verification

Entity subscriptions

Buy several Entity plans together

Settlement transitions

Upsert the customer first

Read usage

Invoices

Alerts