Build headless storefronts with Shopify's Storefront API and Cart API. Use when building custom frontends, setting up Hydrogen, querying products for customer-facing apps, or managing cart operations programmatically. Trigger with phrases like "shopify headless", "shopify storefront api", "shopify hydrogen", "shopify cart api", "headless commerce shopify".
The Storefront API is Shopify's public-facing GraphQL API for customer experiences. Unlike the Admin API (server-side, privileged), it uses a public access token safe for client-side code. Paired with the Cart API, it powers headless storefronts, mobile apps, and custom buying experiences.
unauthenticated_read_products, unauthenticated_read_collectionsimport { createStorefrontApiClient } from "@shopify/storefront-api-client";
const client = createStorefrontApiClient({
storeDomain: "my-store.myshopify.com",
apiVersion: LATEST_API_VERSION,
publicAccessToken: "your-storefront-public-token", // Safe in browser
});
const { data } = await client.request(CART_CREATE, {
variables: {
input: {
lines: [{ merchandiseId: "gid://shopify/ProductVariant/123", quantity: 2 }],
buyerIdentity: { email: "[email protected]", countryCode: "US" },
},
},
});
// Redirect to data.cartCreate.cart.checkoutUrl to complete purchase
Full cart mutations (cartLinesAdd, cartLinesUpdate, cartLinesRemove, cartDiscountCodesUpdate) in cart-api.md.
// Storefront API schema differs from Admin API — field names are NOT the same
const { data } = await client.request(`
query { products(first: 10) { edges { node {
id title handle availableForSale
priceRange { minVariantPrice { amount currencyCode } }
variants(first: 5) { edges { node {
id title availableForSale
price { amount currencyCode } // MoneyV2 object, not a string
selectedOptions { name value }
}}}
}}}}
`);
| Concern | Storefront API | Admin API |
|---|---|---|
| Token type | Public (safe in browser) | Private (server-only) |
| Rate limiting | Request-based | Query cost-based (1000 pts/sec) |
| Cart/Checkout | Full cart + checkout URL | No cart operations |
| Product data | Customer-facing fields only | Full data + inventory |
| Mutations | Cart, customer, checkout | Full CRUD on all resources |
Detailed comparison in storefront-vs-admin.md. Hydrogen framework setup in hydrogen-patterns.md.
| Error | Cause | Solution |
|---|---|---|
INVALID_STOREFRONT_ACCESS_TOKEN | Token missing, expired, or wrong store | Regenerate in Shopify admin under Headless channel |
THROTTLED | Exceeded request rate limit | Retry with backoff; cache product data |
PRODUCT_NOT_AVAILABLE | Product not published to Headless channel | Publish product to the Headless sales channel |
CART_DOES_NOT_EXIST | Cart ID expired (10-day inactivity) | Create a new cart; don't persist IDs long-term |
Create a cart, add line items, apply discount codes, and redirect to Shopify's hosted checkout using the Storefront Cart API.
See Cart API for the complete cart lifecycle mutations and response shapes.
Set up a new Hydrogen project with Remix loaders, Storefront client configuration, and server-side product queries.
See Hydrogen Patterns for the framework setup and loader patterns.
Decide which API to use based on token type, rate limiting model, available mutations, and data access scope.
See Storefront vs Admin for the detailed comparison.