---
title: "Get Stripe connect URL"
method: GET
path: "/v1/connect/stripe"
tags: ["Connect"]
---

# Get Stripe connect URL

`GET /v1/connect/stripe`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/connect/stripe`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Connect-Token`
- TypeScript: <https://skmtc.dev/zernio/apis/zernio-api/docs/v1/connect/stripe/get.ts> (a function with typed inputs; its response is checked against the schema)

Initiates Stripe Connect OAuth for the customer's own Stripe account, with read-only access. Stripe is a connect-only sales source: each paid charge becomes a `Purchase` event in `GET /v1/events` (source `stripe`), and refunds lower or retract it.

One Stripe account can be connected per profile. Connecting a different account to a profile that already has one redirects with `error=stripe_profile_has_account`.

### Flow

1. Redirect the user to `authUrl`.
2. After authorization, Stripe returns the browser to Zernio's internal callback.
3. Zernio redirects to `redirect_url` (or the dashboard when omitted).

On success the redirect carries `connected=stripe`, `profileId`, `accountId` and `username` (the Stripe account name). On failure it carries `error`, `platform=stripe` and `error_message`.

To match a payment to the ad campaign behind it, set `zrn`, `gclid`, `fbclid` or `utm_*` keys (and optionally `landing_url`) in the metadata of the Checkout Session, PaymentIntent or subscription.

## Query parameters

- `profileId` string, required
- `redirect_url` string
- `reconnectAccountId` string

## Response `200`

OAuth authorization URL and authenticated state

- object
  - `authUrl` string, uri, required: Stripe URL to open in the user agent.
  - `state` string, required: Authenticated, expiring OAuth state handled by the callback.

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `402`: Payment method or enterprise contract required: the authenticated account hit a billing gate before the connection could proceed. Switch on `reason` to render the right prompt: - `free_tier_exceeded`: the team has connected more accounts than the free tier allows. Add a payment method to continue (billed per additional connected account). - `twitter_passthrough`: connecting an X account requires a card on file, even the 1st one, because X API calls are passed through per call. Prepaid-balance accounts never get it: they pay X calls from the balance. - `enterprise_required`: the team's enterprise contract sets a connected-account cap and it has been reached. Self-service teams have NO cap (the $1/account rate continues at any scale). The user already has a card on file; this gate is about contract terms. - `card_verification_required`: the card on file was flagged at add time (prepaid, or issued in a different country than the billing address). A one-time verification charge of `details.verification_amount_cents` (USD) is pending; it is credited to the team's usage balance, not a fee. **What to do:** redirect the end-user to `dashboard_url`. - `free_tier_exceeded`, `twitter_passthrough`, `card_verification_required`: it opens the Zernio billing page (the add-payment-method drawer, or the verification step). The request succeeds once the card is on file (or verified, or paid). - `enterprise_required`: it opens the enterprise contact form (not the billing tab), to adjust the contract's limit.
- `403`: API key does not have access to this profile, or the key is read-only.
- `404`: Profile not found or access denied.
- `503`: Stripe Connect is not configured.

## Changes

- **2026-11-11** `05cafa483b36`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/connect/stripe/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/8b8e15c91ce3?raw)