stapel-billing
Payments and billing: per-user credit wallets held as expiry-aware credit lots over an immutable ledger, reservations (hold/capture/release) for work priced only after it runs, partial charges that record what a wallet could not cover as a collectable debt, plan bundles granted with or without a payment provider, one-off credit packages and subscription plans, Stripe-backed checkout, customer portal and refund clawback, idempotent webhooks and a service-to-service debit endpoint.
Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.
Install
pip install stapel-billing
At a glance
| Fact | Value |
|---|---|
| Version | 0.14.0 |
| Python | >=3.11 (3.11, 3.12, 3.13, 3.14) |
| HTTP operations | 10 |
| Config axes | 1 |
| Usage surface | 42 |
| Extension points | 6 |
| Error codes | 56 |
| Fleet dependencies | stapel-auth (optional) · stapel-core |
Documentation
Errors: English · Español · Русский · OpenAPI · capabilities.json · llms.txt (for agents)
Quick start
# settings.py
INSTALLED_APPS = [
...
'stapel_billing',
]
from stapel_billing.tasks import get_billing_beat_schedule
CELERY_BEAT_SCHEDULE = {
**get_billing_beat_schedule(), # credit expiry, hold sweep, reconcile
}
Register the beat schedule (or run the three callables in stapel_billing.tasks
from your own cron): credits granted with an expiry only expire because
something runs. System check stapel_billing.W105 says so if nothing does.
Wallets are lots
A wallet is a set of CreditLot rows — each one knows where its credits came
from (purchase, subscription, grant, adjustment, hold_release) and
when they die (expires_at, NULL = never). Spend walks the lots
expiring-soonest first, so a subscription bundle is used before the
non-expiring credits a customer paid cash for. Wallet.balance is a
maintained cache of that total, recomputed from the lots inside the same row
lock as every mutation.
from stapel_billing import credit, debit, hold, capture, release
from stapel_billing.models import LotSource, TransactionType
credit(user=user, credits=3000, type=TransactionType.SUBSCRIPTION_BONUS,
source=LotSource.SUBSCRIPTION, expires_at=sub.current_period_end)
held = hold(user=user, credits=15, type=TransactionType.AI_CHARGE,
idempotency_key=f"mic:{recording_id}")
try:
used = do_the_work()
except Exception:
release(hold_id=held.id) # credits go back with their original expiry
else:
capture(hold_id=held.id, actual_credits=used)
Bus events
Emits
| payment.completed | schema | A payment transaction completed successfully. |
| payment.failed | schema | A payment attempt was declined. Nothing was granted, so nothing is clawed back — the fact exists to be told to the payer. |
| subscription.changed | schema | User subscription plan or status changed. Carries cancel_at_period_end, which no consumer can infer from status. |
Consumes
| user.deleted | schema |
| user.deletion_initiated | schema |
This module also subscribes to its own payment.completed, payment.failed
and subscription.changed — see stapel_billing/notifications.py. That is not
a loop: the emit records that money moved, and the subscriber turns it into the
letter the payer is owed. It lives here rather than in each host because the
gap is identical in every host that installs this library, and the template it
asks for lives in stapel-notifications (≥ 0.20.0) because copy, channels and
languages are that module's job and not this one's.
License
MIT — see LICENSE.
This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.
1 maintainer
Release files for stapel-billing 0.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| stapel_billing-0.14.0.tar.gz | 219.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stapel_billing-0.14.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 394.0 kB
Release files / stapel_billing-0.14.0.tar.gz
| Download URL | stapel_billing-0.14.0.tar.gz |
|---|---|
| Size | 219.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a6d5f633a2bb6065dcc94cfabc3736c46df0831daea926c5ef200347da89257
|
|
BLAKE2b-256 checksum How to use checksums |
936ad422db3907074e1a170384ea6328efd9339ab347fbec0d0fbd84978dcfb0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency logRelease files / stapel_billing-0.14.0-py3-none-any.whl
| Download URL | stapel_billing-0.14.0-py3-none-any.whl |
|---|---|
| Size | 174.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
38fcccd83b69e495758825d4c0890004eb623d2db666debbe387854452f3f858
|
|
BLAKE2b-256 checksum How to use checksums |
21c4df3b52ad2afcf3cdefb80a484d3a45dcfd797e4405659d70f83386e1cfbe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency log
