Billing And Entitlements

SPAPS projects subscriptions, checkout payments, manual grants, and crypto payments into entitlements. Applications check those grants by feature key and user or resource scope, rather than interpreting each payment event.

Mental Model

Hosted Surfaces

Surface	Customer use
Products	Read the products exposed to the application
Checkout	Create hosted payment flows without handling raw payment data
Subscriptions	Read customer subscription state
Entitlements	Make application access decisions from the SPAPS projection
Billing portal	Send an authenticated customer to provider-managed subscription controls

Example Access Check Shape


curl --fail-with-body \
  -H "X-API-Key: $SPAPS_API_KEY" \
  --get --data-urlencode "user_id=<user-uuid>" \
  --data-urlencode "entitlement_key=<feature-key>" \
  https://api.sweetpotato.dev/api/entitlements/check

Replace the placeholders with an existing user’s UUID and the feature key. This server-side example uses a staging secret key. Browser checks use a publishable key, an allowed Origin, and the signed-in user’s bearer token; the server restricts them to that user.

Operational Pitfalls

Do not let a downstream app infer paid access directly from Stripe. SPAPS should project payment state into entitlements so every app consumes the same access contract.

Test checkout and entitlement projection in the hosted staging application first.
Treat a successful browser redirect as navigation, not proof that payment settled.
Keep production price IDs, credentials, and webhook destinations out of staging configuration.