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.