API keys and the SitesPlaced Developer API

SitesPlaced has an API. An API is a way for another program to read and change your store's data without a person clicking through the dashboard. A developer can use it to build a custom website that shows your SitesPlaced products and sends shoppers to your SitesPlaced checkout, or to send orders in from another system. The API is on the free plan.

What an API key is

An API key is a password for a program. Your developer's code sends the key with every request, and SitesPlaced uses it to work out which store the request is for and what it is allowed to do. Anyone who holds the key can do whatever the key allows, so treat it the way you treat a password.

A key belongs to one store. A store can hold up to 20 keys, so you can give each website or script its own key and switch one off later without breaking the others.

Create a key

1. 1Open your store in the dashboard and go to Settings → Developer.
2. 2Create a new key and give it a name that says what it is for, such as “Website” or “Accounts script”. The name is only for you.
3. 3Choose the kind: secret for code that runs on a server, or publishable for code that runs in a web page. The next section explains the difference.
4. 4Tick the permissions the program needs and nothing more. A site that only shows products does not need permission to change orders.
5. 5For a publishable key, add the allowed websites: the addresses the key may be used from, such as https://myshop.com. You can add up to 10.
6. 6Copy the key and hand it to your developer in a safe way. It is shown once. After you close the box, SitesPlaced cannot show it again.

These are the permissions a key can have:

• orders:read: read orders.
• orders:write: create and update orders.
• products:read: read products.
• products:write: send products from another platform. This is used by the WooCommerce and Shopify connections.
• checkout:write: prepare a checkout for a shopper.
• tracking:read: look up order tracking.
• webhooks:write: manage webhooks. A webhook is a message SitesPlaced sends to your developer's server when something happens, such as a new order.
• connection:manage: manage a connected store. This is used by the WooCommerce and Shopify connections.

Secret key or publishable key

• A secret key starts with sp_live_sk_. It belongs on a server only. It can do whatever permissions you gave it, including reading customer details on orders. If a secret key is sent from a web browser, SitesPlaced refuses the request.
• A publishable key starts with sp_live_pk_. It is safe to put in the code of a web page, where any visitor can read it. It can only do three things: read your published products, prepare a checkout, and look up order tracking. It only works from the websites on its allowed list.

If your developer is not sure which one to ask for: a page that runs in the shopper's browser gets a publishable key. Anything that reads or changes orders gets a secret key and runs on a server.

Keep a key safe

• SitesPlaced stores only a hash of each key. A hash is a one-way fingerprint: it lets us check a key that is sent to us, but the key cannot be worked back out of it. This is why a key is shown once and never again.
• Do not paste a secret key into a web page, a mobile app, a public code repository, a chat group or a screenshot.
• Do not put a key in a web address. The API refuses a key sent in the URL, because addresses end up in browser history and server logs. The key goes in a request header.
• Give each program its own key with only the permissions it needs.
• If you stop working with a developer or an agency, revoke the keys they held.

The keys on this screen are the ones SitesPlaced gives you. The keys you paste in from payment gateways and couriers are a different thing, covered in How we handle your keys.

Revoke a key

To revoke a key, open Settings → Developer, find the key by its name and revoke it. Each key is revoked on its own, so the others keep working. A program that still uses the revoked key gets an “unauthorized” reply (code 401) on every request. If you revoke the wrong key, create a new one and give that to your developer.

Limits

• On the free plan, a secret key can make 60 requests a minute. On a paid store plan (Growth or AI Co-founder) that is 300 a minute. See pricing.
• A publishable key can make 600 requests a minute on the free plan and 3,000 on a paid store plan, and each visitor is limited to 30 a minute on the free plan and 60 on a paid store plan.
• A program that goes over the limit gets a “rate limited” reply (code 429) that says how many seconds to wait.
• If a paid plan ends, the limits drop back to the free ones. Nothing is deleted.

Where the reference lives

• Developer hub: what can be built, and a first request in three steps.
• API reference: every route, with request and response examples, webhooks and how to check their signatures.
• WooCommerce plugin and Shopify connector (early access).
• A machine-readable description of the API (the OpenAPI format) is at https://sitesplaced.com/api/v1/openapi.json. Developer tools can read it to generate code.

Troubleshooting

• Unauthorized (401). The key is missing, mistyped or revoked. Check that the whole key was copied, with no space at the end.
• Forbidden (403). The key is not allowed to do this. The usual causes: a secret key used from a web browser, a publishable key used from a website that is not on its allowed list, or a key without the permission the request needs.
• Rate limited (429). Too many requests in one minute. The program should wait for the number of seconds in the reply and try again.
• Product requests are refused. The store must be published before the product routes work.
• Asking us for help. Every reply from the API carries a request id that starts with req_. Send it with your message on the contact page and we can find the exact request.