Fourthwall API Integration Reference | Developer & Build Documentation

The Dual API Model

Fourthwall provides two distinct API tiers designed for separate operational roles:

API Tier	Base Endpoint	Primary Purpose	Required Credentials
Storefront API	`https://storefront-api.fourthwall.com/v1`	Public catalog browsing, product query, cart creation, checkout generation	`NEXT_PUBLIC_FW_STOREFRONT_TOKEN`
Platform Open API	`https://api.fourthwall.com/open-api/v1.0`	Administrative backend product creation, media library upload, catalog ingestion	`FOURTHWALL_ACCESS_TOKEN` or Basic Auth

Storefront API (v1)

Used directly by the storefront client to query data:

Endpoints Used in Storefront:

GET /collections: Fetches all published collections.
GET /collections/{handle}/products: Returns products in a collection filtered by currency.
GET /products/{handle}: Returns a single product with full variant tree.
POST /carts: Initializes a new persistent cart session.
GET /carts/{id}: Retrieves an existing cart by ID.
POST /carts/{id}/add: Adds merchandise items to an existing cart.
POST /carts/{id}/change: Updates item quantities or variants.
POST /carts/{id}/remove: Removes line items.
GET /shop: Returns shop metadata and public checkout domains.

Platform Open API (v1.0)

Used by lib/fourthwall/importer.ts and scripts/import-artworks-to-fourthwall.ts for syncing catalog artworks to the Fourthwall merchant backend:

Product Creation Payload Contract:

json

{
  "name": "Greetings from Austin",
  "slug": "greetings-from-austin",
  "description": "Original fine artwork Greetings from Austin by Rory Skagen...",
  "type": "physical",
  "status": "ACTIVE",
  "tags": ["greetings-from-austin", "mural", "texas", "Austin Iconic & Texas Pop", "Enamel"],
  "images": [
    {
      "url": "https://res.cloudinary.com/xjilp2pq/image/upload/v1787076996/GreetingsfromAustin.jpg",
      "width": 2100,
      "height": 1400,
      "alt": "Greetings from Austin by Rory Skagen - Enamel"
    }
  ],
  "variants": [
    {
      "name": "12" x 18" Archival Print",
      "sku": "RS-GREETING-1",
      "price": 55.00,
      "currency": "USD",
      "inventoryType": "UNLIMITED",
      "attributes": { "size": "12" x 18"", "medium": "Enamel" }
    }
  ]
}

Authentication Methods

Our integration supports three distinct authentication schemes depending on your configuration:

1. Bearer Token (Recommended for Service Accounts):

```http

Authorization: Bearer

```

2. Basic Authentication (API Key + Secret):

```http

Authorization: Basic base64(:)

```

3. Storefront Header:

```http

X-Storefront-Token:

```

Cart & Checkout Lifecycle

Cart sessions are stored in an encrypted HTTP-only cookie keyed to the storefront token:

// components/cart/actions.ts
const tokenHash = cleanEnv(process.env.NEXT_PUBLIC_FW_STOREFRONT_TOKEN) || 'default';
const cookieStore = await cookies();
cookieStore.set(`${tokenHash}/cartId`, cartId);

When a customer clicks Proceed to Checkout, they are redirected to Fourthwall's hosted, secure checkout domain (NEXT_PUBLIC_FW_CHECKOUT or shop.roryskagen.com).