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_collections
import { 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: "customer@example.com", 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.