Skip to content

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

  • 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.
  1. Fetch the store’s own description of itself:

    Terminal window
    curl https://your-store.example/api/v1/store/config -H 'Accept: application/json'
  2. Read capabilities from 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.

  3. Read currency, locales and legal fields from the same payload instead of hard-coding them.

  4. Probe GET /storefront/access to learn whether the public store is open, in maintenance, or visible to you because you hold a preview token or a staff session.

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.

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.

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.

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.

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.