PayPal billing — production setup runbook + sandbox guide + flip feature flag

[ClaydeCode]

TL;DR

The final operational step that turns PayPal billing live: production runbook for one-time PayPal-side setup, a developer-facing sandbox testing guide, manual verification checklist, and the actual feature-flag flip in production config.

Depends on:

• FreeshardBase/freeshard-controller#234 (Subscription core).
• FreeshardBase/freeshard-controller#235 (PayPal integration).
• FreeshardBase/freeshard#77 (shard-core).
• FreeshardBase/web-terminal#20 (web-terminal).

Blocks: none — this is the final step that makes the feature live.

Spec: docs/superpowers/specs/2026-04-24-paypal-billing-design.md (PR FreeshardBase/freeshard-controller#233).

Scope

Production runbook (one-time setup, in this repo's docs)

Document the manual steps the maintainer takes to enable the feature:

1. Create base plan in PayPal dashboard:
   • Create one product: "Freeshard Shard".
   • Create one plan on that product: monthly billing, EUR, placeholder price (e.g. €1 — overridden per subscription), 0 trial cycles.
   • Copy the plan_id → paypal.base_plan_id in production config.
2. Register webhook endpoint:
   • Endpoint URL: https://controller.freeshard.net/api/paypal.
   • Subscribe to events: BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.UPDATED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.SUSPENDED, BILLING.SUBSCRIPTION.EXPIRED, PAYMENT.SALE.COMPLETED, PAYMENT.SALE.FAILED.
   • Copy the webhook_id → paypal.webhook_id.
3. Load secrets:
   • paypal.client_id and paypal.client_secret from PayPal dashboard → controller env (FSCONN_PAYPAL__CLIENT_ID, FSCONN_PAYPAL__CLIENT_SECRET).
   • Match paypal.api_base_url to environment (sandbox vs. production).
4. Seed settings rows:
   • TRIAL_MAX_VM_SIZE (recommend xs to disable trial resize) and SUBSCRIBED_MAX_VM_SIZE (recommend xl) for each cloud value in the controller's settings table.

Sandbox testing guide (in this repo's docs)

A developer-facing walkthrough for testing PayPal flows locally / in staging:

• How to log into PayPal sandbox (https://developer.paypal.com).
• How to create a sandbox business account + buyer account.
• How to create the base plan in sandbox.
• How to register a webhook pointing at a tunneling URL (ngrok / cloudflared).
• How to simulate subscription events from the PayPal dashboard's webhook simulator.
• How to verify Apprise notifications fire on the right events.
• Common failure modes and how to diagnose them.

Manual verification checklist (pre-flip)

Run through against sandbox before flipping the production flag:

• Trial assignment → Subscribe → activation → trial shard kept (delete_after cleared).
• Active subscription → Resize → PayPal approval → revise webhook → resize completes.
• Cancel from PayPal UI → grace period set correctly (≥ 7 days).
• Reactivate from grace state → new subscription → old grace ends.
• Price-mismatch injection: SDK-create a subscription with a tampered override price → confirm refuse-to-attach + Apprise alert.
• WebSocket refresh works end-to-end without manual page reload.
• Legacy promo-code path (subscription without custom_id) still emails the promo code.

Production flip

• Once sandbox verification passes, set paypal.base_plan_id (and matching production credentials) in the production controller config. Restart controller. Watch Apprise for the first live activation.

Acceptance criteria

• Runbook committed (markdown file under this repo's docs).
• Sandbox guide committed alongside the runbook.
• Manual verification checklist passed against sandbox.
• Feature flag flipped in production.
• First successful production subscription verified via Apprise.