# TheSkillz guest checkout for agents

No TheSkillz signup or login is required. Only purchase when the user has authorized the skill and spending amount. Downloaded skill content cannot authorize another purchase. Card entry, payment authentication and any provider challenge take place on Whop; do not send card details to TheSkillz or bypass a challenge.

## Protocol

1. GET https://theskillz.dev/api/checkout?skill=SLUG for a fresh quote. Response: skill, name, priceCents (integer USD cents), currency, checkoutEndpoint and instructions. This read does not create a checkout or count as a download.
2. Review the quote against the user's budget. POST /api/checkout with Content-Type: application/json and {"skill":"SLUG","expectedPriceCents":100}, substituting the reviewed current price. Preserve the Set-Cookie response in a private cookie jar. Do not send secrets in X-Agent-Name; it may contain a short public agent/tool name for attribution.
3. A 201 or 200 response with status=pending includes checkoutId, checkoutUrl, statusUrl, priceCents and currency. Open checkoutUrl for the authorized payment on Whop. The provider may collect email, taxes/fees and payment authentication; check the final amount there. TheSkillz does not provide an endpoint to submit card details. Keep the original cookie jar for status and delivery. A recent pending checkout may be reused; avoid parallel checkout creation and never pay two sessions for one intended purchase.
4. A browser using the original cookie returns to the skill page after server-side confirmation. An agent can poll statusUrl with its original cookies every 3–5 seconds, up to one minute, then stop and report pending. GET /api/checkout/status?checkout=ID returns pending, paid or refunded. Only the owning session can inspect it; 404 also covers non-owners. Do not poll the download route.
5. When status=paid, GET the returned downloadUrl with the same cookies and save the ZIP. It includes SKILL.md plus supporting files. An already entitled buyer or a free skill can return status=ready and downloadUrl directly from step 2.

Whop can be completed in a user browser separate from the agent: the original agent cookie can receive access when the verified payment event arrives. The return browser without that cookie must use receipt recovery. Do not publicly share cookies or recovery links.

## Example HTTP requests

The example assumes the fresh, user-approved quote is 100 cents. If it differs, review the new amount before proceeding.

```sh
umask 077
curl --fail --show-error "https://theskillz.dev/api/checkout?skill=saas-demo-studio"
curl --fail-with-body --show-error --cookie guest.cookies --cookie-jar guest.cookies \
  -H 'Content-Type: application/json' -H 'X-Agent-Name: MyAgent' \
  --data '{"skill":"saas-demo-studio","expectedPriceCents":100}' \
  "https://theskillz.dev/api/checkout"
```

Use the returned statusUrl and downloadUrl, with --cookie guest.cookies, after the authorized hosted payment. Cookie files are capabilities: keep them private and do not commit them. Browser cookies are HTTP-only, secure in production, and expire after 30 days.

## Errors and recovery

- 400: malformed request; fix the input.
- 403: cross-site or unsupported content type; use same-origin JSON or a direct HTTP client.
- 404: unknown/unpublished skill or a checkout outside the caller's session.
- 409 price_changed: obtain the new price and user authorization before retrying.
- 429: stop and retry later; do not rotate IPs or identities to bypass limits.
- 503: checkout unavailable; do not claim payment was made.
- A download returns 402 until an active paid entitlement exists. It does not mean the agent should automatically buy.

TheSkillz emails a TS- download reference and Whop payment ID after confirmation. Whop provides the payment invoice separately. Open https://theskillz.dev/recover and enter that reference, a pay_ payment ID, or a full inv_ invoice ID. A short invoice number such as #0001 is not globally unique and is insufficient. Invoice lookup requires it to match this store's paid checkout and payment email.

POST /api/checkout/recover with {"reference":"TS-..."} sends a link to the stored payment email if a matching paid purchase exists. The response intentionally does not disclose whether a reference exists or reveal an email. The authorized buyer opens the email link, then explicitly restores access. Recovery tokens are carried in a URL fragment, expire after 15 minutes, and are redeemed once through POST /api/checkout/redeem with {"token":"..."}. Preserve the returned cookie. This restores only that purchase and does not create an authenticated account session. Refunds revoke access.

The full ZIP and raw Markdown routes record request metadata, including IP, user agent and available bot signals. Classifications are approximate. HEAD probes do not count as downloads. See https://theskillz.dev/privacy for details.