SubscriptionPlans.md

Subscription plans

Plans define the recurring product, price and billing interval sold through a checkout. A plan is not a customer's subscription. Examples accept the client from setup.

Create a monthly plan

from vatly import VatlyClient
from vatly.models import CreateSubscriptionPlanRequest


def example(client: VatlyClient):
    return client.subscription_plans.create(
        CreateSubscriptionPlanRequest(
            name="Pro",
            description="Monthly access to Pro",
            base_price={"value": "19.00", "currency": "EUR"},
            product_type="saas",
            interval="month",
            interval_count=1,
        )
    )

Input field	Type	Required?
name, description	string	Yes
base_price	EUR money, e.g. {"value": "19.00", "currency": "EUR"}	Yes
product_type	"saas"	Yes
interval	"day", "week", "month", "year"	Yes
interval_count	positive integer	Yes
tax_behavior	"exclusive" or "inclusive"	No

Use decimal strings, never floats, for money. The current creation contract uses EUR. Model fields are snake_case; dictionary inputs use basePrice, productType, intervalCount and taxBehavior.

Find, update and archive

from vatly import VatlyClient


def example(client: VatlyClient):
    plans = list(client.subscription_plans.list_all({"includeArchived": True, "limit": 25}))
    plan = client.subscription_plans.get("subscription_plan_example")
    updated = client.subscription_plans.update(plan.id, {"name": "Pro monthly"})
    client.subscription_plans.archive(updated.id)
    restored = client.subscription_plans.unarchive(updated.id)
    return plans, restored

Archiving prevents new sales, not existing renewals. archive() returns None; unarchive() returns the plan. Test changes are auto-approved; live changes may require approval.

Response field	Meaning
id	subscription_plan_... catalog ID
name, description, base_price	Product and price
interval, interval_count	Billing cadence
testmode, links	Mode and resource links

Plan API reference · All methods