# Octany Integration Docs

Reference documentation for integrating Octany as your billing engine.
The audience is engineers and LLM coding agents — every page is dense,
example-driven, and avoids marketing prose.

## Start here

| Doc | When to read |
| --- | --- |
| [`integration.md`](integration.md) | First-time setup. Auth, account scoping, base URL, errors, pagination, locale. |
| [`frontend.md`](frontend.md) | Browser-side integration: Fundraising embeds, Checkout URL + params, embeddable cart (`window.Octany`), and Classic widget. |
| [`openapi.yaml`](openapi.yaml) | Machine-readable API contract. Drop into Stoplight, Swagger UI, Postman, or feed to a code generator. |
| [`../website/api.html`](../website/api.html) | Human-readable API reference with endpoint groups, request bodies, response examples, and resource payload shapes. |
| [`webhooks.md`](webhooks.md) | Full event catalog, payload examples, and `Octany-Signature` verification recipe. |
| [`migrating-from-cashier.md`](migrating-from-cashier.md) | Concept-by-concept Stripe Cashier → Octany mapping. Read before scoping a migration. |
| [`llms.txt`](../llms.txt) | One-screen summary linking to everything above. Designed to be pasted into an LLM's context. |

## What's in scope today

The public Octany API exposes:

- **Subscriptions** — list, retrieve, cancel, swap product, list/create one-off orders
- **Products** — full CRUD
- **Orders** — retrieve
- **Webhook endpoints** — register URL to receive signed events
- **Integration API** (separate auth, partner-platform-only) — user/SSO/account onboarding

## Known gaps (filed for upcoming work)

These are documented honestly so integrators don't waste time looking:

- **No checkout-session API** — checkout is a hosted web page. You construct the URL server-side and redirect.
- **No customer-portal API endpoint** — billing-portal URLs come back inline on the subscription resource (`update_card_url`, `invoices_url`, `cancel_url`). They are signed, time-limited links.
- **No `Idempotency-Key` support** on POST endpoints. Retry-safety is the integrator's responsibility today.
- **`POST /webhooks/endpoints` doesn't return the secret in the response.** Fetch it from the admin UI ("Developers → Webhooks") after creation. This will be fixed.
- **3DS / payment-method management** is handled by the hosted checkout; no API surface for direct card collection.

When something here is wrong or missing, open a PR against this folder.