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.is_active()            # True for active/trialing
ent.has("imports")
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_url.
• Webhook verification: verify_push_signature(raw_body, header, secret) — validates a push and returns the parsed event (raises on a bad signature).

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_url; 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_url, which redirects to the hosted PDF after an ownership check).

set_default_payment_method, remove_payment_method, set_subscription_payment_method, and invoice_pdf_url 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. 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.

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