External Website API

Put your stock on your own website

SheetSurfer already keeps your Google Sheet and your marketplaces in step. The API is the same stock, read and written from your own site or your own tools, so the two never disagree. Everything comes back as JSON and cross-origin requests are allowed, so your site can call it straight from the browser.

Stock on your own site

Read your live stock, prices and photographs straight from SheetSurfer, so your own shop always shows what you actually hold.

Sales back the other way

When something sells on your site, send the sale in. Stock comes down, a row lands in your Solds tab, and the item comes off eBay when nothing is left.

Add and change stock

Create an item or change its stock, price or photographs from your own tools. The sheet row and the marketplace listing follow.

Calling it

Every request goes to the one address below, with your key in an x-api-key header. What you are asking for is set by the resource in the address and by the method — GET to read, POST to add, PATCH to change.

Endpoint address

The same address for every endpoint — what differs is the resource and the method.

Getting a key

The API is the External Website API Access add-on, £12 a month on top of any plan. It is taken on its own or alongside a plan, and cancelled on its own without touching the plan. Your keys live under Settings, then Widgets, then API — that is where you make one, name it, lock it to your site's address, and choose which endpoints it may use.

Reading is on from the start. The three that change things — adding an item, changing one, recording a sale — are switched off on a new key until you turn them on, so a key that leaks onto a public page cannot be used to alter your stock.

See the plans

The endpoints

Seven of them, one address. Replace YOUR_KEY with a key from your account.

GET

List your stock

Every item you hold, with a search, a sheet pair filter and paging.

https://sheetsurfer.uk/functions/sheetSyncApi?resource=inventory

limit: How many to return. 50 by default, 200 at most.
offset: How many to skip, for paging through a big catalogue.
group: One sheet pair only.
q: Text to look for in the title, the SKU or the game.
in_stock: 1 leaves out anything with none left.

Comes back as { items, count, total, has_more, currency }

curl "https://sheetsurfer.uk/functions/sheetSyncApi?resource=inventory&in_stock=1&limit=50" \
  -H "x-api-key: YOUR_KEY"

GET

Get one item

A single item's full details, by id or by SKU.

https://sheetsurfer.uk/functions/sheetSyncApi?resource=inventory&sku=ABC-1

id: The item's id in SheetSurfer.
sku: Or its SKU. One of the two is enough.

Comes back as { item }

curl "https://sheetsurfer.uk/functions/sheetSyncApi?resource=inventory&sku=YOUR-SKU" \
  -H "x-api-key: YOUR_KEY"

GET

List your sheet pairs

Your stock categories, so a site can group and filter by them.

https://sheetsurfer.uk/functions/sheetSyncApi?resource=groups

Comes back as { groups, count }

curl "https://sheetsurfer.uk/functions/sheetSyncApi?resource=groups" \
  -H "x-api-key: YOUR_KEY"

GET

List your sales

Recent sales across every marketplace, newest first.

https://sheetsurfer.uk/functions/sheetSyncApi?resource=solds

limit: How many to return. 25 by default, 200 at most.
offset: How many to skip, for paging.
group: One sheet pair only.

Comes back as { sales, count, total, has_more, currency }

curl "https://sheetsurfer.uk/functions/sheetSyncApi?resource=solds&limit=25" \
  -H "x-api-key: YOUR_KEY"

POST

Add an item

switch on first

Add stock from the site. The item gets its own row in your sheet.

https://sheetsurfer.uk/functions/sheetSyncApi?resource=inventory

title: Needed. What the item is called.
sku: Your own reference for it.
quantity: How many you have. 0 lists nothing.
price: What you are asking for it.
condition: e.g. NEW, USED_GOOD, CARD_NEAR_MINT.
category: Your own grouping.
images: A list of image addresses.
custom: An object of your own extra fields.
group_id: Which sheet pair it belongs in.

Comes back as { item } — 201

curl -X POST "https://sheetsurfer.uk/functions/sheetSyncApi?resource=inventory" \
  -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Example item","sku":"ABC-1","quantity":3,"price":9.99}'

PATCH

Update an item

switch on first

Change stock, price, title, images or category. Your sheet row and the eBay listing follow.

https://sheetsurfer.uk/functions/sheetSyncApi?resource=inventory&sku=ABC-1

id or sku: Which item — in the body or in the address.
quantity: The new stock figure.
price: The new price.
title: A new title.
condition: A new condition.
category: A new grouping.
images: A new list of image addresses.
custom: Extra fields to merge in.

Comes back as { item }

curl -X PATCH "https://sheetsurfer.uk/functions/sheetSyncApi?resource=inventory&sku=YOUR-SKU" \
  -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"quantity":2,"price":8.5}'

POST

Record a sale

switch on first

Log a sale made on your site: stock comes down, a row is written to your Solds tab, and the item comes off eBay if nothing is left.

https://sheetsurfer.uk/functions/sheetSyncApi?resource=solds

sku or title: One of the two is needed.
quantity: How many went. 1 by default.
sale_price: What it went for.
order_id: Your own order reference.
sale_date: When it sold. Now, by default.
buyer: Who bought it.

Comes back as { sale, item } — 201

curl -X POST "https://sheetsurfer.uk/functions/sheetSyncApi?resource=solds" \
  -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"sku":"ABC-1","quantity":1,"sale_price":9.99,"order_id":"WEB-1042"}'

When something is wrong

Anything that goes wrong comes back as JSON with an error saying what it was, alongside the status code.

401: The key is missing, or isn't one we know.
402: The key's account has no active API subscription.
403: The key is switched off, locked to a different site, or that endpoint isn't on for it.
404: Nothing is served for that resource and method, or no item matched.
400: The request was missing something it needed, such as a title.