Reference
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 |
| Customer accounts | /v1/storefront/customer/* | Publishable key + customer session |
| Management API | /v1/products, /v1/orders, /v1/inventory… | Secret key, scoped |
| Server API | /v1/customers, /v1/payment-links, /v1/transactions, /v1/balance, /v1/payouts, /v1/classrooms | Secret key, scoped |
| 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
TypeScript
// 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.customer.register(input) mercestack.customer.login(input)
mercestack.customer.googleSignIn(t) mercestack.customer.logout()
mercestack.customer.me() mercestack.customer.update(input)
mercestack.customer.addresses.add() mercestack.customer.orders()
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
TypeScript
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