> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://api-docs.papertracc.com/storefront/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server. # Overview The Storefront API is for building your own shop on Papertracc. Your site keeps its own design and pages; Papertracc supplies the catalogue, prices, blog, newsletter signup, cart and checkout for one sales channel. ## Before you start 1. **Plan.** The workspace's subscription plan must include the Open API. 2. **Sales channel.** In Papertracc, create a sales channel of type Storefront API (Headless). Its handle is the value you send in the `channel` header. 3. **Content.** Make products, collections and blogs available on that channel, and give the channel a price book and the countries it sells to. 4. **Quotes.** Turn on the Quotes service in the workspace. Checkout records each order as a draft quote. ## Headers | Header | Required | Value | | --------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `Authorization` | Always | `Bearer` followed by a public or secret key. | | `identity` | Always | The workspace identity. | | `channel` | Always | The handle of the Storefront API sales channel. | | `cart-token` | Cart and checkout requests, except creating a cart | The token returned when the cart was created. | | `shopper-token` | Account, order history, wishlist and review requests; optional on checkout and contact | The session token returned when the shopper signed in. See [Account](/storefront/account). | | `client-ip` | Optional, secret keys only | The shopper's IP address, when your server calls on a shopper's behalf. | ```bash curl "https://api.papertracc.com/v1/store/shop" \ -H "Authorization: Bearer $API_KEY" \ -H "identity: $WORKSPACE_IDENTITY" \ -H "channel: $CHANNEL_HANDLE" ``` ## Which key to use Every Storefront endpoint accepts both kinds of key. * **Public key** for calls made from the shopper's browser. Outside the Storefront it can only read three Core lists, so it is safe to ship in your site's code. * **Secret key** for calls made from your server. Keep it out of the browser. Storefront endpoints do not check the key owner's role. Everything they return is what a shopper is meant to see, and everything they accept is what a shopper is meant to do. ## Countries and currency A channel can sell to several countries, each with its own price book. Pass `country` to price products for that market; without it, prices follow the channel's default country. A cart takes its country when it is created and its currency from that country's prices. `country` accepts a two- or three-letter code, so `NG` and `NGA` both mean Nigeria, and `GB` and `GBR` both mean the United Kingdom. Responses always use the three-letter code. ## Calling from your server Rate limits on sign-in, cart creation, checkout, reviews, comments, contact messages and signup are counted per shopper, using the caller's IP address. When your server makes the call, every shopper would otherwise look like one address. Sign server calls with a secret key and send the shopper's address in `client-ip`. The header is ignored on public-key requests. Public-key requests are limited to 10 a second from one address, which a server-rendered site reaches quickly because every page view comes from the same server. Secret-key requests are limited to 50 a second for each key instead. Use the secret key for server-side calls, and cache catalogue and blog responses so that page views do not turn into one request each. ## What is not included yet * **Card and USSD payment.** When the workspace has Papertracc Checkout on, checkout returns a `checkout_url` where the shopper pays by bank transfer. Other methods are not offered yet. When checkout is off, collect payment with your own provider, or let the merchant invoice the shopper from Papertracc. See [Pagination](/pagination) for how lists are paged and [Errors](/errors) for status codes. ## Docs - [Overview](https://api-docs.papertracc.com/storefront/shop.md) - [Overview](https://api-docs.papertracc.com/storefront/catalogue.md) - [Overview](https://api-docs.papertracc.com/storefront/blog.md) - [Overview](https://api-docs.papertracc.com/storefront/newsletter.md) - [Overview](https://api-docs.papertracc.com/storefront/cart.md) - [Overview](https://api-docs.papertracc.com/storefront/checkout.md) - [Overview](https://api-docs.papertracc.com/storefront/account.md) - [Overview](https://api-docs.papertracc.com/storefront/orders.md) - [Overview](https://api-docs.papertracc.com/storefront/reviews.md) - [Overview](https://api-docs.papertracc.com/storefront/contact.md) - [Overview](https://api-docs.papertracc.com/storefront/requests.md) ## API Docs - Storefront > Shop [Get Shop](https://api-docs.papertracc.com/storefront/shop/get-shop.md) - Storefront > Catalogue > Products [List Products](https://api-docs.papertracc.com/storefront/catalogue/products/list-products.md) - Storefront > Catalogue > Products [Get Product](https://api-docs.papertracc.com/storefront/catalogue/products/get-product.md) - Storefront > Catalogue > Products [List Recommendations](https://api-docs.papertracc.com/storefront/catalogue/products/list-recommendations.md) - Storefront > Catalogue > Collections [List Collections](https://api-docs.papertracc.com/storefront/catalogue/collections/list-collections.md) - Storefront > Catalogue > Collections [Get Collection](https://api-docs.papertracc.com/storefront/catalogue/collections/get-collection.md) - Storefront > Blog > Blogs [List Blogs](https://api-docs.papertracc.com/storefront/blog/blogs/list-blogs.md) - Storefront > Blog > Blogs [Get Blog](https://api-docs.papertracc.com/storefront/blog/blogs/get-blog.md) - Storefront > Blog > Articles [List Articles](https://api-docs.papertracc.com/storefront/blog/articles/list-articles.md) - Storefront > Blog > Articles [List Article Tags](https://api-docs.papertracc.com/storefront/blog/articles/list-article-tags.md) - Storefront > Blog > Articles [Get Article](https://api-docs.papertracc.com/storefront/blog/articles/get-article.md) - Storefront > Blog > Articles [List Related Articles](https://api-docs.papertracc.com/storefront/blog/articles/list-related-articles.md) - Storefront > Blog > Articles [Count Article View](https://api-docs.papertracc.com/storefront/blog/articles/count-article-view.md) - Storefront > Blog > Comments [List Comments](https://api-docs.papertracc.com/storefront/blog/comments/list-comments.md) - Storefront > Blog > Comments [Create Comment](https://api-docs.papertracc.com/storefront/blog/comments/create-comment.md) - Storefront > Newsletter [Subscribe](https://api-docs.papertracc.com/storefront/newsletter/subscribe.md) - Storefront > Cart [Get Cart](https://api-docs.papertracc.com/storefront/cart/get-cart.md) - Storefront > Cart [Create Cart](https://api-docs.papertracc.com/storefront/cart/create-cart.md) - Storefront > Cart [Update Cart](https://api-docs.papertracc.com/storefront/cart/update-cart.md) - Storefront > Cart [Add Cart Item](https://api-docs.papertracc.com/storefront/cart/add-cart-item.md) - Storefront > Cart [Clear Cart](https://api-docs.papertracc.com/storefront/cart/clear-cart.md) - Storefront > Cart [Remove Cart Item](https://api-docs.papertracc.com/storefront/cart/remove-cart-item.md) - Storefront > Cart [Update Cart Item](https://api-docs.papertracc.com/storefront/cart/update-cart-item.md) - Storefront > Checkout [Get Layaway Options](https://api-docs.papertracc.com/storefront/checkout/get-layaway-options.md) - Storefront > Checkout [Get Delivery Options](https://api-docs.papertracc.com/storefront/checkout/get-delivery-options.md) - Storefront > Checkout [Get Delivery Areas](https://api-docs.papertracc.com/storefront/checkout/get-delivery-areas.md) - Storefront > Checkout [Checkout Cart](https://api-docs.papertracc.com/storefront/checkout/checkout.md) - Storefront > Account > Sign IN [Request Sign-in Code](https://api-docs.papertracc.com/storefront/account/sign-in/request-code.md) - Storefront > Account > Sign IN [Sign In](https://api-docs.papertracc.com/storefront/account/sign-in/sign-in.md) - Storefront > Account > Sign IN [Sign Out](https://api-docs.papertracc.com/storefront/account/sign-in/sign-out.md) - Storefront > Account > Profile [Get Account](https://api-docs.papertracc.com/storefront/account/profile/get-account.md) - Storefront > Account > Profile [Update Account](https://api-docs.papertracc.com/storefront/account/profile/update-account.md) - Storefront > Account > Addresses [List Addresses](https://api-docs.papertracc.com/storefront/account/addresses/list-addresses.md) - Storefront > Account > Addresses [Create Address](https://api-docs.papertracc.com/storefront/account/addresses/create-address.md) - Storefront > Account > Addresses [Delete Address](https://api-docs.papertracc.com/storefront/account/addresses/delete-address.md) - Storefront > Account > Addresses [Update Address](https://api-docs.papertracc.com/storefront/account/addresses/update-address.md) - Storefront > Account > Wishlist [Get Wishlist](https://api-docs.papertracc.com/storefront/account/wishlist/get-wishlist.md) - Storefront > Account > Wishlist [Add To Wishlist](https://api-docs.papertracc.com/storefront/account/wishlist/add-to-wishlist.md) - Storefront > Account > Wishlist [Remove From Wishlist](https://api-docs.papertracc.com/storefront/account/wishlist/remove-from-wishlist.md) - Storefront > Account > Measurements [List Measurements](https://api-docs.papertracc.com/storefront/account/measurements/list-measurements.md) - Storefront > Account > Measurements [Save Measurements](https://api-docs.papertracc.com/storefront/account/measurements/save-measurements.md) - Storefront > Account > Measurements [Delete Measurements](https://api-docs.papertracc.com/storefront/account/measurements/delete-measurements.md) - Storefront > Orders [List Orders](https://api-docs.papertracc.com/storefront/orders/list-orders.md) - Storefront > Orders [Get Order](https://api-docs.papertracc.com/storefront/orders/get-order.md) - Storefront > Orders [Look Up Order](https://api-docs.papertracc.com/storefront/orders/lookup-order.md) - Storefront > Orders [Renew Payment Link](https://api-docs.papertracc.com/storefront/orders/renew-payment-link.md) - Storefront > Reviews [List Reviews](https://api-docs.papertracc.com/storefront/reviews/list-reviews.md) - Storefront > Reviews [Create Review](https://api-docs.papertracc.com/storefront/reviews/create-review.md) - Storefront > Contact [Send Message](https://api-docs.papertracc.com/storefront/contact/send-message.md) - Storefront > Requests [Get Request Form](https://api-docs.papertracc.com/storefront/requests/get-request-form.md) - Storefront > Requests [Get Request Availability](https://api-docs.papertracc.com/storefront/requests/get-request-availability.md) - Storefront > Requests [Upload Request Picture](https://api-docs.papertracc.com/storefront/requests/upload-request-picture.md) - Storefront > Requests [Create Request](https://api-docs.papertracc.com/storefront/requests/create-request.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://api-docs.papertracc.com/openapi.json) - [OpenAPI YAML](https://api-docs.papertracc.com/openapi.yaml)