List on Shopify covers all the ways to connect a store. This is the manual for the deepest one, level C, where your catalog and your cart render on PAY THE DØLLS and a buyer only leaves at the final checkout step.
Headless means the storefront and the commerce engine are separate. Shopify keeps doing everything that is hard, which is most of it. We render the pages. Nothing about your store moves, and nothing about your store changes.
Who owns what
| Shopify keeps | PTD renders |
|---|---|
| Products, variants, prices, SKUs | Your catalog, in the PTD design system |
| Inventory and stock levels | Product pages and the variant picker |
| Orders, refunds, customer records | Browse, search and discovery |
| Fulfilment and carrier integrations | The cart and its drawer |
| Taxes, shipping rules, discount codes | The handoff into your checkout |
| The checkout itself, and the money | Nothing after the buyer clicks it |
What you install
One free first-party app, roughly ten minutes.
- Shopify Admin → Apps → search Headless, published by Shopify. Install it. This is not a custom app and not a Partners app.
- Apps → Headless → Create a storefront. Name it anything.
PTDis fine. - On its overview, find Storefront API → Public access token. Copy it and send it to us.
That token is the entire handoff. There is no second credential and no webhook required for headless itself, though the paid-order webhook from level B is worth keeping if you already run it, because it is what makes the monthly invoice authoritative rather than reconciled.
Why this token is low stakes
A Storefront public access token is designed to be public. It ships to browsers by design, which is why it lives in a NEXT_PUBLIC_ variable on our side and why we are relaxed about it in a way we are not about anything else in the stack.
Its scope is read-only catalog plus the ability to create and modify a cart. It cannot read an order, cannot read a customer, cannot see personal data, and has no administrative power whatsoever. It is a strictly smaller grant than the read-only Admin token used at level B.
These are the permissions to enable on the app's Storefront API permissions panel, and no others:
unauthenticated_read_product_listingsunauthenticated_read_product_inventory· so sold-out variants show as sold outunauthenticated_read_product_tagsunauthenticated_read_collection_listingsunauthenticated_read_checkouts· required for the cartunauthenticated_write_checkouts· required for the cart
How the cart actually works
The cart is Shopify's, created and mutated through the Storefront API. We hold nothing but an identifier.
buyer opens your brand page on PTD
→ no cart yet, we hold no state
buyer adds an item
→ we call Shopify's cartCreate, get back { id, checkoutUrl }
→ we store ONLY that id, in an httpOnly cookie, 14 days
→ the drawer slides open
buyer adds more
→ we read the cookie and call cartLinesAdd
buyer clicks checkout
→ we send them to cart.checkoutUrl, on YOUR domain
→ your checkout takes the payment, your Shopify owns the order
→ we are out of the loop entirely from this pointThe cookie holds an opaque cart id and nothing else. No line items, no prices, no buyer details. Shopify expires an idle cart after about ten days; when ours points at one that is gone, we clear the cookie and start a fresh cart rather than showing an error.
A variant that sells out mid-session is rejected by Shopify at the add-to-cart call, which is correct. We surface that as a message on the button rather than letting the buyer carry a phantom line item into your checkout.
The checkout handoff
Checkout is the one screen we do not render, and we would rather be plain about that than let you discover it at launch. The buyer leaves PTD and lands on your Shopify checkout. This is not a limitation we chose. A fully custom checkout requires Shopify Plus with checkout extensibility, which is an enterprise line item most brands have no reason to carry.
What softens it is that Shopify's checkout is themeable. Under Settings → Checkout → Customize you set the logo, typeface, colours and button styling. Buyers who have been browsing in your world stay in it. If you want the URL to match too, point a checkout subdomain at Shopify and the transition reads as one site.
Upgrading from click-out
If you are already listed at level A, moving to headless changes one row in our brand registry. Your URLs do not change, your listing does not come down, and there is no re-onboarding.
- You install the Headless app and send the Storefront token.
- We flip your registry entry from the public-catalog type to the headless one and attach your store domain and token.
- Your brand page stops reading the cached public catalog and starts reading the Storefront API. Stock goes real-time, and add-to-cart appears.
It reverses just as cheaply. If headless is not earning its keep, we move the row back and you are on click-out again the same day.
Your own subdomain
There is a further step where your headless storefront runs on your domain rather than under ours, so a buyer never sees paythedolls.com in the address bar. You point a subdomain at our host, we map that hostname to your brand, and every request rewrites internally to your brand page.
proxy.ts is built and runs today for our own shop subdomain. Extending it per partner is a small change, but no partner is on it, and we are not going to describe it as available while that is true. Ask if you want it and we will scope it honestly.What headless does not give you
- A custom checkout.Covered above. Shopify's, themed to you.
- Customer accounts on PTD. Order history and logins stay on your Shopify. We do not mirror accounts and have no permission to read them.
- Your marketing automation. Abandoned-cart mail, flows and segments run from your Shopify exactly as they do now. A cart built on PTD is a normal Shopify cart, so those flows keep firing.
- A different fee. The rate is the same at every level, and it is on Fees. Headless is a better buyer experience, not a different commercial deal.
Is it actually running
The pipeline is live and it renders our own houses today, which is the only reason we are comfortable offering it. The Storefront API client, the cart actions and the drawer are the same code paths whether the catalog belongs to us or to you. The only difference is which token the request carries.
No partner brand is on headless yet. Partners on the marketplace today are on the zero-touch public catalog, which is the right default and the one we open with. Headless is worth the ten minutes once PTD is sending you enough traffic that the extra step in the journey is costing you orders.
Not on Shopify?
Then this page does not apply, and we would rather say so than imply support that does not exist. Headless here is Shopify-specific, top to bottom. The click-out tile works with any store on any platform because it ingests nothing at all. Tell us what you are on when you apply, and either we list you that way or we build with you instead. See Launch a store.