Fetching Products

The Storefront API organizes products into collections. There is no standalone “List Products” endpoint—instead, you fetch products through collections.

The `all` Collection

Every shop has a built-in all collection that contains all public products. This is the easiest way to get all products:

// Get all products
const res = await fetch(
  "https://storefront-api.fourthwall.com/v1/collections/all/products?storefront_token=YOUR_TOKEN"
);
const { results, paging } = await res.json();

Common Patterns

Get all products (paginated)

async function getAllProducts(token) {
  const products = [];
  let page = 0;
  let hasMore = true;

  while (hasMore) {
    const res = await fetch(
      `https://storefront-api.fourthwall.com/v1/collections/all/products?storefront_token=${token}&page=${page}&size=50`
    );
    const data = await res.json();
    products.push(...data.results);
    hasMore = data.paging.hasNextPage;
    page++;
  }

  return products;
}

Get products from a specific collection

const res = await fetch(
  "https://storefront-api.fourthwall.com/v1/collections/merch/products?storefront_token=YOUR_TOKEN"
);

Get a single product by slug

Use this when you already know the product slug (e.g., from a URL like /products/cool-t-shirt):

const res = await fetch(
  "https://storefront-api.fourthwall.com/v1/products/cool-t-shirt?storefront_token=YOUR_TOKEN"
);

Bundles

A shop can sell bundles - a fixed set of products sold together for one price. The product endpoints return bundles alongside regular products, so every result is one of two shapes, discriminated by type:

`type`	What you get	How to add it to a cart
`PRODUCT`	A regular product with purchasable `variants`	one item with the variant `id`
`BUNDLE`	A bundle: `price`, `compareAtPrice`, `pricingStrategy` on the root object and the products it consists of under `offers` (each a full product with its own `variants`). A bundle has no `variants` of its own.	one item per product in `offers`, all with the same `bundleId` - see Adding a bundle

{
  "type": "BUNDLE",
  "id": "de91c4b0-762d-4556-85fd-272dff4bf28f",
  "name": "Bundle midnight",
  "slug": "bundle-midnight",
  "state": { "type": "AVAILABLE" },
  "price": { "value": 21.42, "currency": "USD" },
  "compareAtPrice": { "value": 30.60, "currency": "USD" },
  "pricingStrategy": { "type": "DISCOUNT_BASED", "discountPercentage": 30 },
  "offers": [
    { "type": "PRODUCT", "id": "c9f416d9-…", "name": "Hat", "variants": [ { "id": "5ffbc1e0-…", "unitPrice": { "value": 18.65, "currency": "USD" } } ] },
    { "type": "PRODUCT", "id": "15ccdbb0-…", "name": "Mug", "variants": [ { "id": "ada8978c-…", "unitPrice": { "value": 11.95, "currency": "USD" } } ] }
  ]
}

price is the bundle price for the cheapest selection of variants, converted to the requested currency. compareAtPrice is the undiscounted sum of the products and is null when the creator disabled it or the bundle is not discounted.
pricingStrategy is one of SAME_AS_INDIVIDUAL (sum of the products), DISCOUNT_BASED (discountPercentage off the sum) or FIXED_PRICE (price).
state is SOLD_OUT when the creator marked the bundle as sold out or any of its products is unavailable.

Displaying the price for a selection

price is the bundle price for the cheapest selection of variants. When the bundled products have variants with different prices (say a 3XL shirt costs more than S), recompute the price client-side whenever the customer changes a variant - the response contains everything you need: the pricingStrategy and the raw unitPrice of every variant, already converted to the requested currency:

// selectedVariantIds: { [offerId]: variantId } - the customer's current selection
function bundlePrice(bundle, selectedVariantIds) {
  const sum = bundle.offers.reduce((acc, offer) => {
    const variant =
      offer.variants.find((v) => v.id === selectedVariantIds[offer.id]) ?? offer.variants[0];
    return acc + variant.unitPrice.value;
  }, 0);

  switch (bundle.pricingStrategy.type) {
    case "SAME_AS_INDIVIDUAL":
      return round2(sum);
    case "DISCOUNT_BASED":
      return round2(sum * (1 - bundle.pricingStrategy.discountPercentage / 100));
    case "FIXED_PRICE":
      return bundle.pricingStrategy.price.value; // the selection does not change the price
  }
}
const round2 = (v) => Math.round(v * 100) / 100;

The upcharge for a more expensive variant flows into the sum, so a DISCOUNT_BASED bundle discounts it too - the same math the checkout applies to the variants actually in the cart. Round once, at the end, to the currency’s scale.

This is a display-time preview. The binding amount is always computed server-side from the items in the cart; when requesting a currency other than the shop’s, the preview can differ from the cart by at most one cent due to per-variant conversion rounding.

A bundle and the products it contains can both be members of the same collection, in which case the products appear twice in a listing: standalone and inside offers. Control this by composing your collections (for example a collection without the bundled products, or one without the bundle).

Why Collections?

Collections let you:

Organize products into categories (e.g., “Apparel”, “Accessories”)
Control which products appear on your storefront
Create featured or seasonal groupings

The all collection is always available as a catch-all.

Getting Started

API

Products

Webhooks

Streaming

Storefront

Shop APIs

Apps

Channel API

Embedded Sections

HTML Sections

AI

Resources

The `all` Collection

Common Patterns

Get all products (paginated)

Get products from a specific collection

Get a single product by slug

Bundles

Displaying the price for a selection

Why Collections?

​The all Collection

​Common Patterns

​Get all products (paginated)

​Get products from a specific collection

​Get a single product by slug

​Bundles

​Displaying the price for a selection

​Why Collections?

The `all` Collection

Common Patterns

Get all products (paginated)

Get products from a specific collection

Get a single product by slug

Bundles

Displaying the price for a selection

Why Collections?