# PayFlow Studio

> PayFlow Studio finds PayPal subscribers who are about to lapse, drafts the recovery email for a person to approve, and checks whether AI shopping agents can read a store. It is a hackathon project by Amelior Labs. The demo data is synthetic (a fictional merchant, Northwind Notes); the readiness scanner fetches real public pages.

## For AI agents

- You may read data, run a readiness scan, and propose recovery drafts.
- You may not send anything. Every outbound email needs a human to approve it in the app. The API has no send endpoint.
- Lifecycle, playbook and Dev Studio responses carry the header `X-PayFlow-Data: synthetic`. Do not present those figures as a real business's numbers.
- No authentication is needed for the demo API.
- A person can create a read-only API key in Settings. Send it as `Authorization: Bearer pf_live_...` (header only, never in a URL) to GET /api/lifecycle/summary, GET /api/subscriptions/high-risk and GET /api/subscriptions/{id}/events to read their real data. Those responses carry `X-PayFlow-Data: live`. A bad or revoked key returns 401. Limit: 120 requests per minute per key.
- A key does not let you send. The playbook endpoint stays draft-only and on demo data.

## Machine-readable descriptions

- [OpenAPI 3.1 spec](https://payflow.ameliorlabs.ca/openapi.json)
- [Tool manifest](https://payflow.ameliorlabs.ca/.well-known/agent.json)
- [API docs for humans](https://payflow.ameliorlabs.ca/docs)

## Endpoints

- GET /api/lifecycle/summary: active subscriptions, monthly recurring revenue, 30-day churn, high-risk count.
- GET /api/subscriptions/high-risk?limit=50: subscriptions that need attention, with a plain-language riskReason.
- GET /api/subscriptions/{id}/events: normalized PayPal event history for one subscription.
- POST /api/playbooks/recover-failed-payments: body {"subscriptionIds":["sub_001"]}, 1 to 25 ids. Returns drafted emails with status awaiting_approval. Sends nothing.
- GET /api/playbooks/{id}: a drafted playbook.
- POST /api/readiness/scan: body {"storeUrl":"https://example-store.com"}. Scores discoverability, catalog, trust and checkout, and returns copy-ready fixes.
- GET /api/readiness/audits: past audits (empty in demo mode).
- GET /api/dev/scenarios and GET /api/dev/scenarios/{name}/events: replayable PayPal-shaped scenarios and the agent's decisions.

## Pages

- [Subscriber dashboard](https://payflow.ameliorlabs.ca/merchant)
- [Readiness scanner](https://payflow.ameliorlabs.ca/readiness)
- [Revenue Studio](https://payflow.ameliorlabs.ca/studio)
- [Dev Sandbox Studio](https://payflow.ameliorlabs.ca/dev)

## Source

Open source under AGPL-3.0. Built for the PayPal AI Hackathon.