A REST API for your digital goods store

Basics

A key stops working if it expires, if its shop is deactivated, or if the owner's account leaves the Pro and Enterprise plans. The answer is always the same generic 401, so the API never reveals which of those it was.

• Base URL: https://api.shopl.io, with every endpoint under /api/v1.
• Authentication: Authorization: Bearer shp_... on every request.
• Responses use one envelope: {"success": true, "data": ...}.
• Lists are paginated with ?page= (from 1) and ?limit= (default 20, maximum 100).
• Keys are created in the dashboard under Developer, up to 10 per shop. The full key is shown once; Shoplio stores only a hash. Keys can be regenerated or deleted at any time.

Endpoints

• GET /shop: the shop the key belongs to.
• GET /products, GET /products/:id: products with variants and live stock counts.
• POST /products, PATCH /products/:id, POST /products/:id/variants, PATCH /products/:id/variants/:vid: create and update products and variants. There are no delete routes; deleting stays in the dashboard.
• GET /products/:id/stock, POST /products/:id/stock: list unsold stock (decrypted) and add stock. Waiting pre-orders are filled first.
• PATCH and DELETE /products/:id/stock/:sid, POST /products/:id/stock/delete: edit or remove unsold items, up to 500 per bulk call. Sold items are never changed.
• GET /orders, GET /orders/:id, POST /orders/:id/deliver: read orders, including delivered content, and deliver one from your stock.
• GET /customers, GET /customers/:id, POST /customers/:id/balance/add and /subtract: customers and their store balance.
• GET /balance: your crypto balance per gateway and currency, with a USD valuation.

Scopes

There are ten scopes: read_products, write_products, read_orders, write_orders, fulfill_orders, read_stock, write_stock, edit_stock, delete_stock and read_analytics. You tick them when you create a key and can change them later. The three that destroy stock or hand out goods (edit_stock, delete_stock and fulfill_orders) are never granted unless you tick them.

read_orders returns the exact content each buyer received, decrypted, and read_stock returns unsold stock. Treat a key with either scope as holding your inventory.

Rate limits and retries

Each key can make 60 requests a minute. Editing and deleting stock has a stricter bucket of 20 a minute, and order delivery has its own bucket of 60 a minute. Writes to the same product are serialised: a 409 with Retry-After: 5 means another change to that product was in flight and nothing was written, so retrying is always correct. Delivering an order is idempotent: calling it again for a delivered order returns success with "already_delivered": true and delivers nothing more.

Typical uses

• Catalogue sync: create products hidden ("is_active": false), push their stock, then publish them with a PATCH, so the storefront never shows an empty product.
• Supplier restocks: push new keys on a schedule with "notify": true, so waiting pre-orders are filled and restock alerts go out.
• External fulfilment: when an order waits as out of stock, push stock for it and call the deliver endpoint.
• Support tools: credit or debit a customer's store balance from your own help desk.
• Reporting: read orders and your balance per gateway into your own books.

Example: push stock from a supplier feed

POST https://api.shopl.io/api/v1/products/{product_id}/stock with a JSON body of {"items": ["KEY-1", "KEY-2"], "variant_id": "...", "notify": true}. variant_id is required when the product has variants. With notify set, the storefront cache is refreshed and your restock alerts fire; it is off by default. The key needs the write_stock scope.

What the API does not do

Shoplio does not send outgoing webhooks for new orders; poll GET /orders instead. There is no file upload: product images take an already-hosted URL. Withdrawals, payout wallets, API keys and shop deletion are not available through the API.

Related

More features