Storefront API
The storefront API is the public face of a store: everything a shopper’s browser needs to browse a catalog, fill a cart, pay, and then manage their own orders. It is the same surface the supplied themes run on, which is the useful guarantee — anything a MyShopie theme can do, a storefront you build yourself can do too.
Plans: All plans
Prerequisites
Section titled “Prerequisites”- Your store domain. Every path below is relative to
https://{your-store-domain}/api/v1. - Nothing else for the public reads. The cart needs a guest token, which the API issues; the account surface needs a shopper token from Authentication.
Start with store config
Section titled “Start with store config”-
Fetch the store’s own description of itself:
Terminal window curl https://your-store.example/api/v1/store/config -H 'Accept: application/json' -
Read
capabilitiesfrom the response. It reports which features this store actually has — gift cards, subscriptions, wholesale, pickup, loyalty — so your UI renders what exists rather than offering a gift-card field on a store with no gift cards. -
Read currency, locales and legal fields from the same payload instead of hard-coding them.
-
Probe
GET /storefront/accessto learn whether the public store is open, in maintenance, or visible to you because you hold a preview token or a staff session.
Catalog and content
Section titled “Catalog and content”All of these are public reads on the 180-per-minute lane.
| Endpoint | Returns |
|---|---|
GET /categories, /categories/navigation |
The category tree, and a navigation-shaped version of it |
GET /categories/by-slug/{slug}, /{id}, /{id}/attributes |
One category, and the attributes to build facets from |
GET /brands, /brands/{id}, /brands/typeahead |
Brands, and an autocomplete source |
GET /collections, /collections/by-slug/{slug} |
Curated collections |
GET /products, GET /products/{id} |
The catalog and product detail |
GET /products/{id}/related |
Related products for a PDP |
GET /products/hints |
Search autocomplete — its own 60-per-minute lane |
GET /search/multi |
One query across products, categories, brands and content |
GET /products/{product}/reviews, /reviews/summary |
Reviews for a product, and its rating rollup |
POST /products/{product}/reviews |
Submit a review; needs a shopper session or a review token |
GET /reviews |
Reviews across the store, for a testimonials section |
GET /announcements, /banners, /faqs, /social-links |
Storefront content blocks |
GET /store/pages/{slug} |
A CMS page, including the legal pages |
GET /store/blog-posts, /{slug} |
The blog |
GET /markets |
Enabled markets and their presentment currencies |
GET /store/shipping-rates |
Rates, for a pre-checkout estimate |
POST /store/pickup-locations |
Locations that accept collection |
GET /translations, /translations/locales |
Merchant-authored translations and the store’s locales |
See Languages for how a shopper’s locale is chosen and which content is translatable.
The cart
Section titled “The cart”A cart is identified by a guest token until a shopper signs in. The cart endpoints return one; send it
back as the X-Guest-Token header on every later call.
| Endpoint | Does |
|---|---|
GET /cart |
Read the cart |
POST /cart/items, PUT, DELETE |
Add, change quantity, remove |
POST /cart/evaluate |
Re-price the cart — promotions, taxes, totals — without committing anything |
POST /apply-coupon |
Apply a coupon code |
POST /cart/loyalty/apply, DELETE /cart/loyalty |
Spend or release loyalty points |
POST /cart/evaluate is the endpoint to lean on: pricing, promotions and tax are all decided on the server,
so a storefront should never compute a total itself and risk disagreeing with checkout.
Checkout
Section titled “Checkout”| Endpoint | Does |
|---|---|
GET /checkout/payment-methods |
Which methods this store offers |
POST /checkout/check-email |
Whether this email already has an account |
GET /checkout/saved-addresses, POST /checkout/save-address |
A signed-in shopper’s addresses |
POST /checkout/create-intent, /create-checkout-session |
Start a Stripe payment |
POST /checkout/express/create-intent, /create-order-intent, /shipping-rates |
Apple Pay and Google Pay |
POST /checkout/confirm-payment-intent, /confirm-redirect-payment |
Finish a payment, including a hosted-gateway return |
POST /checkout/apply-gift-card, DELETE /checkout/gift-card |
Gift cards, where the plan includes them |
POST /checkout/place-order |
Place the order |
POST /checkout/set-password |
Turn a guest purchase into an account after the fact |
GET /verifyCheckoutSession |
Confirm a returning Stripe session |
Checkout and the payment-request endpoints share a 20-per-minute lane. That is ample for a shopper and deliberately tight for a script.
Payment requests — the POST /payment-requests/{token}/… family — back the pay-by-link flow, including
the QR code on a printed invoice, which resolves through GET /public-invoices/{token}. Price negotiation
runs through POST /checkout/start, /{order}/negotiate, /negotiation and /pay.
The shopper’s own account
Section titled “The shopper’s own account”These need a customer token, and reach only that shopper’s data.
| Area | Endpoints |
|---|---|
| Profile | GET /customer/me, PATCH /customer/me, logout, logout-all, set-password, change-password, resend-verification |
| Account closure | POST /customer/request-account-deletion, /delete-account |
| Orders | GET /customer/orders, /{order}, invoices, POST /reorder, POST /cancel |
| Returns | GET /return-eligibility, POST /return-requests |
| Collection | GET /customer/orders/{order}/pickup-seed — the shopper’s own code seed, so their device renders the pickup QR |
| Addresses | CRUD plus PUT /default |
| Wishlist | List, add, remove |
| Saved cards | List and remove saved Stripe payment methods |
| Loyalty | GET /loyalty/summary, /history, /rewards |
| Digital goods | GET /customer/digital-library, GET /{token}/download |
| Subscriptions | Start, pause, cancel, resume |
| Notifications | Preferences, and the in-account feed |
Wholesale buyers get more on the same guard — companies, addresses, applications, statements, order approvals and quotes — behind the wholesale app. See B2B & wholesale.
Each of these degrades gracefully: a store with no loyalty program answers the loyalty endpoints with an empty or disabled state rather than erroring, so one storefront build serves stores with different features switched on.
Common problems
Section titled “Common problems”The cart is empty on the next request. The guest token was not sent back. It must travel on every cart and checkout call.
Totals differ between my page and checkout. The storefront computed them locally. Use
POST /cart/evaluate and render what it returns.
A product 404s that exists in admin. It is a draft, or out of the requested scope. Public reads only return published records.
Gift-card endpoints return 403. The plan does not include gift cards. See Gift cards & vouchers.
Everything public returns 503. Maintenance mode. Check GET /storefront/access.
429 on search. Autocomplete hints have their own 60-per-minute limit. Debounce the input.
A review submission is rejected. Reviews need a shopper session or a review token from the post-purchase email.
Can I build my own storefront on the MyShopie API?
Yes. Every endpoint the supplied themes use is a public tenant endpoint: catalog, search, cart, checkout,
payment and the shopper account surface. Start from GET /store/config, which reports the store’s currency,
locales, legal details and the capability flags that tell you which features to render.
How does a cart work before the shopper signs in?
The cart endpoints return a guest token. Send it back on every later cart or checkout call as the
X-Guest-Token header. The cart belongs to that token, so losing it means losing the cart — it is not tied
to the IP address or to a cookie you control.
Which endpoints need no authentication at all? Store config, the capability probe, categories, brands, collections, products and product detail, search, reviews, announcements, banners, FAQs, CMS pages, blog posts, social links and shipping rates. The cart and checkout also work for a guest, carrying the guest token instead of a login.
Why do catalog calls suddenly return 503?
The store has maintenance mode on. Public catalog, cart and checkout return 503 in that state, while store
config, authentication and the preview-token endpoint keep working. GET /storefront/access tells you which
state you are in without inferring it from an error.
