7.4 KiB
AI Export Pro — FastAPI SaaS gated by SettleKit
A complete, runnable demo SaaS built with FastAPI. It sells a single paid
feature — an "AI export" — and gates it behind SettleKit entitlements with a
prepaid-credit fallback, using the real SettleKit Python SDK
(import settlekit) and HTTP API. There is no mock data and no fake gate: every
handler calls SettleKit.
Access policy
A POST /ai/export call is allowed when either of these is true:
- The customer holds the
ai_exportentitlement (e.g. an active Pro plan) — verified viaverify_entitlement/entitlements.verify. Unlimited, no credit spent. - The customer has a prepaid credit — one credit is atomically consumed via the SettleKit usage API. Pay-as-you-go.
Otherwise the request is denied with 402 Payment Required (out of credits/entitlement) carrying a friendly upgrade message.
Layout
examples/python-saas/
├── requirements.txt # fastapi, uvicorn, httpx, editable SDK
├── pyproject.toml # optional project metadata
├── README.md
└── app/
├── __init__.py
├── main.py # FastAPI app + routes + error handlers
├── deps.py # the entitlement/credit gate dependency
└── settlekit_client.py # constructs the SDK client + credit helpers
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | / |
Public landing JSON (plan tiers) |
| GET | /healthz |
Liveness probe (no SettleKit call) |
| POST | /signup |
Create a SettleKit customer |
| GET | /me/entitlements?customer_id= |
Show entitlement + credit balance |
| POST | /ai/export?customer_id= |
PAID — gated AI export |
| POST | /billing/grant-credits |
Admin: grant prepaid credits |
Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
SETTLEKIT_API_KEY |
yes | — | Bearer key sent on every request (Authorization). |
SETTLEKIT_ORG_ID |
yes | — | Organization id customers/usage are scoped to. |
SETTLEKIT_API_URL |
no | http://localhost:8787 |
SettleKit API base URL. |
SETTLEKIT_PRODUCT_ID |
no | ai_export |
Product id recorded against metered usage. |
AI_EXPORT_FEATURE |
no | ai_export |
Entitlement feature key the paid route checks. |
The app validates required vars at startup and fails fast with a clear message.
Install & run
The SDK is installed in editable mode from the monorepo via
requirements.txt.
cd examples/python-saas
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# (equivalently: pip install fastapi "uvicorn[standard]" httpx -e ../../sdks/python)
export SETTLEKIT_API_KEY="sk_live_..." # your SettleKit API key
export SETTLEKIT_ORG_ID="org_123" # your organization id
export SETTLEKIT_API_URL="http://localhost:8787" # optional
uvicorn app.main:app --reload --port 8000
Make sure the SettleKit API is running and reachable at SETTLEKIT_API_URL, and
that the ai_export feature/product exists in your organization (so entitlement
verification and credit grants resolve).
Full curl walkthrough
0) Landing page (public)
curl -s http://localhost:8000/ | python3 -m json.tool
1) Sign up — create a customer
curl -s -X POST http://localhost:8000/signup \
-H 'Content-Type: application/json' \
-d '{"email":"ada@example.com","name":"Ada Lovelace"}' | python3 -m json.tool
Copy the returned customerId (referred to as $CID below):
CID="cus_...." # paste the id from the signup response
2) Check access (should be denied — no entitlement, no credits)
curl -s "http://localhost:8000/me/entitlements?customer_id=$CID" | python3 -m json.tool
# -> { "entitled": false, "credits": 0, "canExport": false, "accessVia": "none" }
3) Try the paid export — DENIED (402)
curl -s -i -X POST "http://localhost:8000/ai/export?customer_id=$CID" \
-H 'Content-Type: application/json' \
-d '{"dataset":"q2-sales","fmt":"csv"}'
# -> HTTP/1.1 402 Payment Required
# -> {"error":{"code":"payment_required","message":"AI export is a paid feature...","upgradeUrl":"/#pricing"}}
4a) Grant prepaid credits (admin) — then export is ALLOWED via credit
curl -s -X POST http://localhost:8000/billing/grant-credits \
-H 'Content-Type: application/json' \
-d "{\"customer_id\":\"$CID\",\"credits\":5}" | python3 -m json.tool
curl -s -X POST "http://localhost:8000/ai/export?customer_id=$CID" \
-H 'Content-Type: application/json' \
-d '{"dataset":"q2-sales","fmt":"csv"}' | python3 -m json.tool
# -> { "ok": true, "export": {...}, "access": {"via":"credit","creditsRemaining":4} }
Each successful credit-based export consumes one credit. Re-check the balance:
curl -s "http://localhost:8000/me/entitlements?customer_id=$CID" | python3 -m json.tool
4b) Alternatively, grant the ai_export entitlement — unlimited exports
Grant the entitlement in SettleKit (e.g. by attaching the ai_export feature to
the customer through a Pro subscription or directly via the SettleKit dashboard /
API). Once POST /v1/entitlements/verify returns {"allowed": true} for the
customer, exports succeed without spending credits:
curl -s -X POST "http://localhost:8000/ai/export?customer_id=$CID" \
-H 'Content-Type: application/json' \
-d '{"dataset":"q2-sales","fmt":"json"}' | python3 -m json.tool
# -> { "ok": true, "access": {"via":"entitlement","creditsRemaining":null} }
How it works
app/settlekit_client.pyconstructs one process-wideAsyncSettleKitclient from env vars (closed on app shutdown). It also wraps the prepaid-credit and metered-usage endpoints (/v1/usage/credits,/v1/usage/credits/grant,/v1/usage/credits/consume,/v1/usage/record) through the SDK's low-levelarequestmethod.app/deps.pyis the gate: a FastAPI dependency that (1) callsentitlements.verify, then (2) falls back to atomically consuming a credit. Denials raiseGateDenied; genuine SettleKit/API failures propagate so they surface as 5xx rather than being mistaken for a billing decision.app/main.pywires the routes, validates input with Pydantic, records usage after a successful export, and mapsGateDenied/SettleKitErrorto clean HTTP responses (402/403 for billing, 502 for upstream outages, 500 for misconfiguration).
Notes
- Money is represented as
{"amount": "25.00", "currency": "USDC"}, matching the SettleKit API convention (see the plan tiers onGET /). - The admin route
POST /billing/grant-creditsis left open for the demo. In production, protect it with an admin API key / role check.