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, status, cancelAtPeriodEnd, seats, amount (per-seat price, cents), currency, interval (month/year), currentPeriodStart, currentPeriodEnd, trialEnd, canceledAt, defaultPaymentMethod (all timestamps ISO 8601).
• list_payment_methods → items of id, brand, last4, expMonth, expYear, name (cardholder), isDefault.
• list_invoices → items of id, number, status, amountDue, amountPaid, subtotal, total, tax, paid, currency, created (ISO), hostedInvoiceUrl, invoicePdf.

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.

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