Skip to main content
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 and Storefront API once the shop exists. This guide is about getting that shop created and the creator onboarded.
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 to request access before you build. See Authentication and Requesting an access token.

​
Onboarding flow

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.
cURL
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 Requesting an access token.

​
Creating a shop

A single call provisions the shop, invites the owner, and (optionally) kicks off payout onboarding: 
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"
    }
  }'
FieldRequiredWhat it does
nameYesDisplay name for the new shop.
ownerEmailNoSends an owner invitation to this address. Also used as the payout account email when no payout prefill email is given.
payoutNoProvisions 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.
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.

​
What you get back

FieldUse it for
shopIdScope subsequent Platform API calls to this shop (e.g. the X-ShopId header).
publicTokenBrowser-safe Storefront API reads for the shop.
payoutOnboardingUrlRedirect the creator to finish payout setup (present only when payout was supplied).

​
Shop OAuth tokens

This feature is planned but not yet available. The following describes the intended behavior.
When you create a shop, the response will also include OAuth credentials for it: 
{
  "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, scoped to the shopId.
  • Display the storefront — read products and drive checkout with the Storefront API using the publicToken.
For worked, end-to-end integrations see the Platform integration (single creator) and Agency integration (a fleet of shops) guides.
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.