Merchant onboarding

Onboard a new merchant under your workspace and get a Stripe Connect URL in one round trip.

import { v4 as uuid } from 'uuid'

const res = await fetch(`https://api.swft.co.uk/v2/agencies/${workspaceId}/merchants`, {
  method: 'POST',
  headers: {
    'Authorization':   `Bearer ${SWFT_PARTNER_KEY}`,
    'Content-Type':    'application/json',
    'Idempotency-Key': uuid(),
  },
  body: JSON.stringify({
    name:        'Cobalt Pilates',
    store_url:   'https://cobalt-pilates.com',
    email:       '[email protected]',
    return_url:  'https://unstack.co.uk/studio/cobalt-pilates/stripe-return',
    refresh_url: 'https://unstack.co.uk/studio/cobalt-pilates/stripe-refresh',
  }),
})

const { merchant, stripe } = await res.json()
// Save merchant.id + merchant.api_key on YOUR side; redirect to stripe.onboarding_url
redirectStudio(stripe.onboarding_url)

What happens

1. Swft creates a merchant row with workspace_id = yourWorkspaceId, created_via = 'agency', and fresh api_key / api_secret values.
2. Swft opens a Stripe Standard connected account with metadata.swft_merchant_id set, and stores the stripe_account_id on the merchant.
3. Swft creates a one-time Stripe AccountLink and returns the URL.
4. The studio completes Stripe’s hosted onboarding; Stripe redirects to your return_url when they’re done.

Polling completion

The merchant row’s stripe_onboarded flag flips to true when Stripe reports details_submitted=true. You can either:

• Poll GET /v2/agencies/me with X-Swft-Merchant: <id> and inspect the returned scopes (the legacy stripe_onboarded field is being added to the introspection response in a future date version), OR
• Subscribe to the merchant.stripe.ready webhook event (Phase 2) on the merchant’s webhook URL.

Bundling custom domain

After creation, immediately assign a checkout subdomain in the same wizard step:

await fetch(
  `https://api.swft.co.uk/v2/agencies/${workspaceId}/merchants/${merchant.id}/custom-domain`,
  {
    method:  'POST',
    headers: {
      'Authorization':   `Bearer ${SWFT_PARTNER_KEY}`,
      'Content-Type':    'application/json',
      'Idempotency-Key': uuid(),
    },
    body: JSON.stringify({ subdomain: 'cobalt-pilates' }),
  },
)
// → checkout served from cobalt-pilates.checkouts.unstack.co.uk

subdomain only works once your workspace has a delegated zone — see the DNS delegation guide.