> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from v2

> Map your legacy v2 integration onto the v3 RESTful API.

v3 keeps the same concepts as [v2](/v2/introduction) — products, payments, subscriptions, customers, webhooks — but exposes them as **RESTful, plural, versioned** resources under `/v3/*`.

<Info>
  Existing v2 integrations keep working. The legacy `/api/*` URLs are preserved
  (internally routed to the compatibility layer), so you can migrate endpoint by
  endpoint rather than all at once.
</Info>

### Endpoint mapping

| Action              | v2 (legacy)                       | v3                                                                                                                    |
| ------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Create product      | `POST /api/product/create`        | `POST /v3/products`                                                                                                   |
| Update product      | `PATCH /api/product/:id`          | `PATCH /v3/products/:id`                                                                                              |
| List products       | `GET /api/product/all`            | `GET /v3/products`                                                                                                    |
| Get product         | `GET /api/product/:id`            | `GET /v3/products/:id`                                                                                                |
| Create payment      | `POST /api/payment/create`        | `POST /v3/payments`                                                                                                   |
| List payments       | `GET /api/payment`                | `GET /v3/payments`                                                                                                    |
| Get payment         | `GET /api/payment/:id`            | `GET /v3/payments/:id`                                                                                                |
| Create subscription | `POST /api/subscription/create`   | `POST /v3/subscriptions`                                                                                              |
| List subscriptions  | `GET /api/subscription`           | `GET /v3/subscriptions`                                                                                               |
| Get subscription    | `GET /api/subscription/:id`       | `GET /v3/subscriptions/:id`                                                                                           |
| Cancel subscription | `DELETE /api/subscription/:id`    | `POST /v3/subscriptions/:id/cancel`                                                                                   |
| Refund              | `POST /api/refund/:id`            | *Not yet on the public API* — refunds are issued from the [dashboard](https://dashboard.beta.suby.fi) during v3-beta. |
| List customers      | `GET /api/customer`               | `GET /v3/customers`                                                                                                   |
| Find customer       | `GET /api/customer/search?email=` | `GET /v3/customers?email=`                                                                                            |
| Get customer        | `GET /api/customer/:id`           | `GET /v3/customers/:id`                                                                                               |

### What's new (no v2 equivalent)

* **Setup Intents** (`POST /v3/setup-intents`) — save a customer payment method for later off-session charges.
* **Saved payment methods** (`GET/DELETE /v3/customers/:id/payment-methods`).
* **Checkout Sessions** (`POST /v3/checkout/sessions`) — signed `cs_xxx` hosted-checkout tokens.
* **Balance** (`GET /v3/balance`) — unified balance across card + crypto rails.
* **Webhook Endpoints** (`POST /v3/webhook-endpoints`) — manage outbound webhook destinations and rotate secrets via the API.
* **Analytics** (`GET /v3/analytics`, `GET /v3/products/:id/analytics`, `GET /v3/customers/:id/analytics`).

### What stays the same

* **Authentication** — same `X-Suby-Api-Key` header, same `sk_live_…` / `sk_sandbox_…` keys.
* **Response envelope** — `{ "success": true, "data": … }` on success, `{ "success": false, "error": { code, message } }` on failure.
* **Monetary values** — prices in **cents as strings** (`"999"` = 9.99), fees in basis points, token amounts in smallest unit.
* **Webhook signing** — HMAC-SHA256, `X-Webhook-Signature: v1=<hex>`, 5-minute replay window.

### Migration checklist

<Steps>
  <Step title="Swap base paths">
    Point your client at `/v3/*` and switch to the plural, RESTful resource names above.
  </Step>

  <Step title="Group your method-specific fields">
    On `POST /v3/payments` and `POST /v3/subscriptions`, card and crypto options live in a `card` / `crypto` object rather than flat on the body: `tokenizedInstrument` → `card.tokenizedInstrument`, and `cryptoMode` / `chainId` / `assetId` → `crypto.mode` / `crypto.chainId` / `crypto.assetId`. See the [changelog](/changelog) for the full mapping.
  </Step>

  <Step title="Adjust the cancel verb">
    Subscription cancel is now `POST /v3/subscriptions/:id/cancel` (not `DELETE`). Refunds are not yet exposed on the public v3 API — issue them from the dashboard for now.
  </Step>

  <Step title="Re-register webhook endpoints">
    Create your webhook destinations via `POST /v3/webhook-endpoints` and store the returned `whsec_…` secret.
  </Step>

  <Step title="Test in sandbox">
    Run the full flow with a `sk_sandbox_…` key before flipping production traffic.
  </Step>
</Steps>