Overview | Papertracc Docs

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

Plan. The workspace’s subscription plan must include the Open API.
Sales channel. In Papertracc, create a sales channel of type Storefront API (Headless). Its handle is the value you send in the channel header.
Content. Make products, collections and blogs available on that channel, and give the channel a price book and the countries it sells to.
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.
`client-ip`	Optional, secret keys only	The shopper’s IP address, when your server calls on a shopper’s behalf.

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 for how lists are paged and Errors for status codes.