Subscriptions.md

Subscriptions

A paid checkout containing a subscription plan starts recurring billing. There is no direct subscriptions.create(). Read and manage the resulting subscription ID after establishing who owns it. Examples use the client from setup.

Read and change a subscription

from vatly import RequestOptions, VatlyClient


def example(client: VatlyClient):
    subscription = client.subscriptions.get("subscription_example")
    changed = client.subscriptions.update(
        subscription.id,
        {"subscriptionPlanId": "subscription_plan_pro", "quantity": 2},
        options=RequestOptions(idempotency_key="plan-change:42"),
    )
    return changed.status, changed.scheduled_update

Changes are scheduled by default. Inspect scheduled_update; do not immediately replace the active plan in your application.

Update parameter (wire key)	Purpose
subscriptionPlanId, quantity, price	Send at least one to request a change
applyImmediately	Apply now instead of scheduling
invoiceImmediately, prorate, prorationCharge	Explicit invoicing/proration choices
trialUntil	Optional aware datetime; cannot be the sole change

Cancel, resume and update billing details

These are separate user actions. Only resume during a valid grace period.

from vatly import VatlyClient


def example(client: VatlyClient):
    client.subscriptions.cancel("subscription_example", {"immediately": False})

For a later, separate resume request:

from vatly import VatlyClient


def example(client: VatlyClient):
    return client.subscriptions.resume("subscription_example")

from vatly import VatlyClient


def example(client: VatlyClient):
    link = client.subscriptions.create_billing_update_link(
        "subscription_example",
        {
            "redirectUrlSuccess": "https://app.example.com/billing/success",
            "redirectUrlCanceled": "https://app.example.com/billing/canceled",
        },
    )
    return link.href

Cancellation returns None; resume returns a Subscription. Set immediately=True only when the user intends immediate cancellation. Reuse business idempotency keys with RequestOptions when retrying mutations.

Response field	Meaning
status	Current lifecycle state; inspect it before granting access
customer_id, subscription_plan_id, quantity	Billing identity and current purchase
canceled_at	Cancellation request time, not grace expiry
ended_at	Actual end when present
next_renewal_at, renewed_until, trial_until	Period information; nullable
scheduled_update	Pending changes or None

Do not infer a subscription ID from a plan ID. Initial order lines can still reference plans; this alpha does not consume the proposed related-resources subscription reference. Fluent's guide explains recovery and expiry limits.

Subscription API reference · All methods