vellumcharter

Thin, dependency-free (stdlib-only) server-side client for the VellumCharter entitlements + billing API. Server-side only — it holds a secret API key.

Install

pip install vellumcharter

Requires Python 3.11+.

Usage

from vellumcharter import VellumCharterClient

vellum = VellumCharterClient(
    api_key="vlm_sam.xxxxx",   # keep server-side, never ship to a browser
    tenant_id="sam",
    # base_url defaults to https://api.vellumcharter.com
)

# Gate a feature (cached with a short TTL):
if vellum.can("unit_1", "imports"):
    ...

ent = vellum.get_entitlements("unit_1")
ent.has_access()           # server-authoritative; for reporting, not gating
ent.has("imports")         # gate on THIS
ent.config("trial_days")
ent.found                  # False if the customer has no record (no exception)

A 404 returns an empty EntitlementSet (no exception), so gating never needs a null check.

Async

AsyncVellumCharterClient is the awaitable counterpart — same constructor and methods, each await-ed. Use it from async frameworks (e.g. FastAPI):

from vellumcharter import AsyncVellumCharterClient

vellum = AsyncVellumCharterClient(api_key="vlm_sam.xxxxx", tenant_id="sam")

if await vellum.can("unit_1", "imports"):
    ...

ent = await vellum.get_entitlements("unit_1")
vellum.invalidate("unit_1")   # cache op is synchronous (no await)

What it covers

• Entitlements: get_entitlements, can, opt-in TTL cache + invalidate.
• Checkout / subscriptions: create_checkout, create_setup_checkout, create_subscription, cancel_subscription, get_subscription.
• Provisioning: create_account, create_customer, set_account_status, set_customer_status.
• Billing: list_payment_methods, set_default_payment_method, remove_payment_method, set_subscription_payment_method, list_invoices, invoice_pdf.
• Webhook verification: verify_push_signature(raw_body, header, secret) — validates a push and returns the parsed event (raises on a bad signature).
• Feature flags: flags, flag (default required, keyword-only), global_flags, invalidate_flags — a separate axis from entitlements (see below).

Billing reads return dicts in the server's camelCase shape:

• get_subscription → id (deprecated, removed in 1.0.0), status, cancelAtPeriodEnd, seats, amount (per-seat price, cents), currency, interval (month/year), currentPeriodStart, currentPeriodEnd, trialEnd, canceledAt, defaultPaymentMethod (deprecated, removed in 1.0.0), defaultPaymentMethodRef (an opaque handle, byte-identical to the matching payment method's ref; omitted if it could not be minted — fall back to defaultPaymentMethod; all timestamps ISO 8601).
• list_payment_methods → items of id (deprecated, removed in 1.0.0), ref (opaque, account-bound — send this to the methods below; omitted if it could not be minted, fall back to id), brand, last4, expMonth, expYear, name (cardholder), isDefault.
• list_invoices → items of id (deprecated, removed in 1.0.0), ref (opaque, account-bound — send this to invoice_pdf; omitted if it could not be minted, fall back to id), number, status, amountDue, amountPaid, subtotal, total, tax, paid, currency, created (ISO), hostedInvoiceUrl, invoicePdf (deprecated, removed in 1.0.0 — use invoice_pdf, which returns the PDF bytes after an ownership check).

set_default_payment_method, remove_payment_method, set_subscription_payment_method, and invoice_pdf each take a ref from the calls above; a raw billing-provider id is still accepted in the same argument but is deprecated and removed in 1.0.0.

payment.* push events additionally carry seats and an invoice block (id, number, status, amountDue, amountPaid, currency, hostedInvoiceUrl, invoicePdf) so a dunning notice needs no follow-up read.

payment.succeeded does not mean money moved. A trial start or a trial extension produces a zero-amount invoice that is genuinely paid, so the event fires with invoice["amountPaid"] == 0. Check amountPaid > 0 before treating it as revenue, a receipt, or a fulfilment trigger. invoice.id and invoice.invoicePdf are deprecated the same way as their pull-API counterparts, but the push payload has no ref to migrate onto yet, so their removal is tracked separately (D40, TODO.md) rather than tied to the SDK's 1.0.0.

Feature flags

A second, independent axis from entitlements (D45): a flag says whether a feature is switched on, never whether it was paid for. vellum doesn't consult the customer's plan, tier, modules, or subscription when evaluating one — for "paid and enabled", and the two yourself. Flags are boolean-only by design, and reads are cached separately from entitlements (flag_cache_ttl_ms, default 30s matching cache_ttl_ms — 0 disables), so invalidating one never disturbs the other:

# Every flag for a customer (global values with that customer's overrides applied):
flags = vellum.flags("unit_1")   # Dict[str, bool]

# One flag, with a required, keyword-only fallback — returned both when the
# flag is undefined and when the read fails, so an outage can't silently
# flip every gated feature off (or on) across your app:
enabled = vellum.flag("new-dashboard", "unit_1", default=False)

# Tenant-global values, no customer applied (a scheduled job, a queue worker):
global_flag_values = vellum.global_flags()

# Drop a cached flag read (leaves the entitlements cache untouched):
vellum.invalidate_flags("unit_1")

Available on both clients — AsyncVellumCharterClient awaits each of these the same way as get_entitlements.

Errors

VellumCharterAuthError on 401/403; VellumCharterApiError (with .status / .body) on other non-2xx; VellumCharterSignatureError on a bad push signature. The API key is sent as x-api-key on every request.

API reference

Full endpoint + webhook contract: https://api.vellumcharter.com/openapi.json

Upgrading to 1.0.0

Breaking. Every raw billing-provider id is gone from the contract; objects that need a handle carry an opaque, account-bound ref instead.

Raw ids are no longer accepted on input. set_default_payment_method, remove_payment_method, set_subscription_payment_method and invoice_pdf take a ref; anything else returns 404, deliberately — a 403 would confirm the object exists.

set_subscription_payment_method now returns the updated subscription view rather than {"subscription", "default"}, matching every other subscription mutation.

ref is always present. Through 0.10.0 it could be omitted if the server failed to mint one and you fell back to id; with id gone the server fails closed instead, so a response either has a usable ref or is an error.

Two things did not change: Invoice.hostedInvoiceUrl (a Stripe-hosted payment page, not an identifier) and the inbound billing_customer_id on create_account, which adopts a customer that predates Vellum.

Both clients are affected identically — VellumCharterClient and the async AsyncVellumCharterClient stay in step.