> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.papertracc.com/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.