Choose a billable model
A billable is the saved user, team or company your application has authorized to
buy. Existing models can use Billing() without changing their inheritance.
from vatly_django.billing import Billing
def example(billable):
billing = Billing()
return billing.resources(billable, "subscription")
Pass a saved, already-authorized model instance. Queries include its entity, scope and mode; no customer-ID ownership fallback is used.
Add billing methods to your model
Add helpers such as checkout(), subscribed() and billing_portal() to your
user or team model without adding database columns.
For a model in your teams app, inherit the abstract mixin:
from django.db import models
from vatly_django.mixins import BillableMixin
class Team(BillableMixin):
name = models.CharField(max_length=200)
class Meta:
app_label = "teams"
Keep your model's normal fields and permissions. Run makemigrations teams and
migrate as usual; the mixin itself adds no columns. Do not replace an existing
auth user model just to integrate billing.
| Mixin method | Purpose |
|---|---|
checkout(offer, idempotency_key=...) | Create a hosted purchase |
billing_portal() | Open the bound customer's portal |
subscriptions(), subscribed() | Read owned subscriptions and convenience access state |
cancel_subscription(id, immediately=False) | Request cancellation |
resume_subscription(id) | Resume and refresh the snapshot |
swap_subscription(id, plan_id) | Request a plan change |
billing(scope=...) | Access the underlying facade |
Entity identity is the Django model label plus primary key. Renaming models or changing keys needs a migration of your billing references. Deleting a user does not cascade through these generic billing references; apply your retention policy.