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

# Channel API Integration Guide

> Provision Fourthwall shops and onboard creators programmatically from your platform via the Channel API

The Channel API is Fourthwall's **shop provisioning and onboarding** layer. It
lets your platform create Fourthwall shops for your creators and onboard them
end to end — spin up a shop, invite its owner, set up payouts, and receive the
credentials your platform needs to operate that shop on the creator's behalf.

It answers one question: *how does a new creator get a working Fourthwall shop
from inside your product?* Everything downstream — designing products, building
a storefront, taking checkout — is handled by the
[Platform API](/api-reference/platform) and
[Storefront API](/storefront/overview) once the shop exists. This guide is about
getting that shop created and the creator onboarded.

<Warning>
  The Channel API requires **special access**. It is **invite only** and currently
  in **beta** — there is no self-serve way to obtain credentials. Your channel must
  be explicitly granted access by Fourthwall, which then provisions a dedicated
  `channel.*` client (id + secret) for it. [Reach out to
  Fourthwall](mailto:support@fourthwall.com) to request access before you build.
  See [Authentication](/channel-api/authentication).
</Warning>

## Onboarding flow

```mermaid theme={null}
flowchart TD
    A[Creator starts setup on your platform] --> B{New or existing shop?}
    B -->|New| C[POST /channel-api/v1.0/shops]
    C --> D[Shop created — shopId + publicToken returned]
    C --> E[Owner invited by email]
    C --> F[Payout onboarding URL returned]
    F --> G[Redirect creator to hosted payout onboarding]
    G --> H[Creator returns to your returnUrl]
    B -->|Existing| I[Creator authenticates via OAuth and links their shop]
    D --> J[Shop ready — operate it via Platform & Storefront APIs]
    H --> J
    I --> J
```

A creator either gets a **brand-new shop** your platform provisions for them, or
**links an existing** Fourthwall shop through OAuth. The Channel API owns the
first path — creating and onboarding the new shop.

## Authentication

The Channel API uses OAuth2 **client credentials**. Your channel client
authenticates with its own id and secret; no per-creator authorization step is
required to create shops.

```bash cURL theme={null}
curl -X POST \
  "https://auth.fourthwall.com/auth/realms/Fourthwall/protocol/openid-connect/token" \
  -u "$CHANNEL_CLIENT_ID:$CHANNEL_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
```

Pass the returned `access_token` as a Bearer token on every Channel API request.
Full details — including the HTTP Basic gotcha — are on the
[Authentication](/channel-api/authentication) page.

## Creating a shop

A single call provisions the shop, invites the owner, and (optionally) kicks off
payout onboarding:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.fourthwall.com/channel-api/v1.0/shops" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Nova'\''s Shop",
      "ownerEmail": "nova@example.com",
      "payout": {
        "returnUrl": "https://yourapp.com/onboarding/return",
        "refreshUrl": "https://yourapp.com/onboarding/refresh",
        "country": "US",
        "businessType": "individual"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "shopId": "sh_abc123",
    "shopName": "Nova's Shop",
    "publicToken": "ptkn_xyz789",
    "invitationEmail": "nova@example.com",
    "invitationStatus": "INVITED",
    "payoutOnboardingUrl": "https://connect.fourthwall.com/onboard/..."
  }
  ```
</CodeGroup>

| Field        | Required | What it does                                                                                                            |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `name`       | Yes      | Display name for the new shop.                                                                                          |
| `ownerEmail` | No       | Sends an owner invitation to this address. Also used as the payout account email when no payout prefill email is given. |
| `payout`     | No       | Provisions a connected payout account and returns a hosted onboarding URL.                                              |

## Inviting the owner

Pass `ownerEmail` and Fourthwall sends an owner invitation to the creator. The
response echoes `invitationEmail` and an `invitationStatus` (`INVITED`,
`FAILED`, …). Accepting the invite is how the creator gains direct dashboard
access to the shop your platform created for them.

## Payout onboarding

Include a `payout` object and Fourthwall provisions a connected payout account
and returns a single-use `payoutOnboardingUrl`. Redirect the creator there to
complete identity and bank details in Fourthwall's hosted flow.

* `returnUrl` — where the creator lands when they leave the hosted flow.
* `refreshUrl` — where they land if the link has expired or been reused; mint a
  fresh shop/payout link and redirect again.
* `country` / `businessType` — drive the required verification fields.
* `prefill` — optional values to pre-fill the form so the creator types less.

<Warning>
  Returning to your `returnUrl` means the creator **left** the hosted flow — not
  that the account is verified. Treat the payout account as *pending* and check
  its status separately before relying on payouts.
</Warning>

## What you get back

| Field                 | Use it for                                                                             |
| --------------------- | -------------------------------------------------------------------------------------- |
| `shopId`              | Scope subsequent Platform API calls to this shop (e.g. the `X-ShopId` header).         |
| `publicToken`         | Browser-safe [Storefront API](/storefront/overview) reads for the shop.                |
| `payoutOnboardingUrl` | Redirect the creator to finish payout setup (present only when `payout` was supplied). |

## Shop OAuth tokens

<Warning>
  This feature is **planned but not yet available**. The following describes the
  intended behavior.
</Warning>

When you create a shop, the response will also include OAuth credentials for it:

```json theme={null}
{
  "shopId": "sh_abc123",
  "shopName": "Nova's Shop",
  "publicToken": "ptkn_xyz789",
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "dGhpcyBpcyBh..."
}
```

These let your platform call the Platform API **on behalf of the created shop**
without a separate per-creator OAuth authorization step. The `accessToken` is
short-lived; use the `refreshToken` to renew it.

## After the shop exists

Onboarding is done once the shop is created and the creator is invited. From
there:

* **Manage the shop** — products, orders, analytics — with the
  [Platform API](/api-reference/platform), scoped to the `shopId`.
* **Display the storefront** — read products and drive checkout with the
  [Storefront API](/storefront/overview) using the `publicToken`.

For worked, end-to-end integrations see the
[Platform integration](/channel-api/platform-integration) (single creator) and
[Agency integration](/channel-api/agency-integration) (a fleet of shops) guides.

<Note>
  Across every onboarded shop, Fourthwall acts as **Merchant of Record** —
  handling fulfillment, shipping, tax compliance, payment disputes, and customer
  support — so your platform owns onboarding, not operations.
</Note>