2026-06-17 02:09:36 +03:00
..
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00

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:

  1. The customer holds the ai_export entitlement (e.g. an active Pro plan) — verified via verify_entitlement / entitlements.verify. Unlimited, no credit spent.
  2. 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.py constructs one process-wide AsyncSettleKit client 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-level arequest method.
  • app/deps.py is the gate: a FastAPI dependency that (1) calls entitlements.verify, then (2) falls back to atomically consuming a credit. Denials raise GateDenied; genuine SettleKit/API failures propagate so they surface as 5xx rather than being mistaken for a billing decision.
  • app/main.py wires the routes, validates input with Pydantic, records usage after a successful export, and maps GateDenied / SettleKitError to 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 on GET /).
  • The admin route POST /billing/grant-credits is left open for the demo. In production, protect it with an admin API key / role check.