Skip to main content

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.

Use this endpoint to send a shopper directly into Fourthwall checkout from a URL. It is especially useful when you want to pass product variants directly (products=...) from ads, feeds, or custom links. Base URL: 
https://{shop_domain}/cart/checkout
Recommended direct-products example: 
https://{shop_domain}/cart/checkout?products=11111111-1111-1111-1111-111111111111:1,22222222-2222-2222-2222-222222222222:2&currency=USD
If you already have a Storefront API cart, cartId is also supported: 
https://{shop_domain}/cart/checkout?cartId=22222222-2222-2222-2222-222222222222&currency=USD

​
Request

  • Method: GET
  • Path: /cart/checkout
  • Intended use: Browser redirect links (ads, email, social, product feeds, etc.)
  • Use the root path (/cart/checkout), not a locale-prefixed path.

​
Query Parameters

ParamRequiredDescription
productsNoComma-separated list of cart items in variantId[:quantity] format.
cartIdNoExisting cart ID to checkout. If present and valid, products is ignored.
couponNoPromo code to apply.
currencyNoCheckout currency (for example USD).
cart_originNoCart origin metadata.
utm_*, _ga, _fbp, _fbc, gclid, fbclid, FPIDNoMarketing params are captured and propagated in checkout metadata.

​
products Format

Format: 
products=variantId[:quantity],variantId[:quantity],...
Rules:
  • variantId must be a variant UUID (not product/offer ID).
  • quantity is optional; default is 1.
  • Invalid quantity values fall back to 1.
  • Entries with too many separators (like id:1:extra) are skipped.
  • URL-encoded input is supported.
  • If any entry has an invalid variant UUID, parsing fails and products becomes empty.
Examples: 
?products=11111111-1111-1111-1111-111111111111
?products=11111111-1111-1111-1111-111111111111:2
?products=11111111-1111-1111-1111-111111111111:1,22222222-2222-2222-2222-222222222222:3

​
Behavior

Checkout creation flow:
  1. If products contains valid variant entries, the endpoint can create/update a cart from those products.
  2. If cartId is provided and valid, checkout uses that cart and ignores products.
  3. If both are unavailable (no valid cartId and no valid products), redirect goes to /.
  4. On success, a checkout is created/updated and the shopper is redirected to /checkout/{checkoutId}.
Promo code precedence:
  1. coupon query param
  2. Manually-applied promo already on cart
  3. Automatically applied promo code from a shared link
Currency precedence:
  1. currency query param
  2. Session currency
  3. USD

​
Response

This endpoint responds with redirects:
  • Success: 303 See Other -> /checkout/{checkoutId}
  • Empty/invalid input: 303 See Other -> /
  • Exception path: 303 See Other -> /?error_message=...

​
Google Merchant Center Template

This endpoint supports the Google template pattern: 
https://{shop_domain}/cart/checkout?products={id}:1

​
Example Integration

Direct variant handoff (primary): 
function redirectToDirectCheckout(shopDomain, variantId, quantity = 1, coupon) {
  const params = new URLSearchParams({
    products: `${variantId}:${quantity}`
  });

  if (coupon) params.set("coupon", coupon);

  window.location.href = `https://${shopDomain}/cart/checkout?${params.toString()}`;
}
Cart ID handoff (also supported): 
function redirectCartToCheckout(shopDomain, cartId, currency = "USD") {
  const params = new URLSearchParams({
    cartId,
    currency
  });

  window.location.href = `https://${shopDomain}/cart/checkout?${params.toString()}`;
}