Commerce API
API reference
Endpoints, limits, versioning and the SDK surface.
Endpoints
| Path | Auth | |
|---|---|---|
| Storefront API | /v1/storefront/* | Publishable key |
| Downloads | /v1/downloads/:token | None — single use, ten minutes |
| Developer console | /commerce/developers/* | Workspace session |
Limits
| Rate limit | 600 requests per minute per key, by default |
| Headers | Mercestack-RateLimit-Limit, Mercestack-RateLimit-Remaining |
| Request id | Mercestack-Request-Id, on every response |
| Page size | 24 by default, 100 maximum |
SDK surface
// Simple
mercestack.getStore()
mercestack.getProducts(query) mercestack.getProduct(handleOrId)
mercestack.search(term) mercestack.getCollections()
mercestack.getCategories()
mercestack.getCart() mercestack.addToCart(input)
mercestack.updateCartItem(id, n) mercestack.removeFromCart(id)
mercestack.clearCart() mercestack.applyDiscount(code)
mercestack.applyGiftCard(code) mercestack.removeGiftCard(id)
mercestack.setCustomer(input) mercestack.setShippingAddress(address)
mercestack.checkout(input) mercestack.openCheckout(input)
mercestack.getLibrary(token) mercestack.getDownloadUrl(token, id)
mercestack.on(event, listener)
// Namespaced — the same operations, named after what they touch
mercestack.products.list() mercestack.products.retrieve(handle)
mercestack.cart.addItem() mercestack.cart.token()
mercestack.collections.list() mercestack.library.download()Namespaced methods are bound, so const { addItem } = mercestack.cart works — a destructured method that loses its this is the most common way an SDK surprises someone.
Versioning
/v1 is a promise. Your storefront renders these field names, so renaming one would be an outage on your website, not ours. New fields are added freely; renames and removals mean a new version, and the old one keeps working.
Events you can listen to
const off = mercestack.on("cart.updated", (cart) => {
setCount(cart.itemCount);
});
off(); // on() returns its own unsubscribe
// cart.created · cart.updated · cart.cleared
// checkout.started · order.completed