Shopiza API and webhooks
Connect a Shopiza shop to your own code or to automation tools: read orders, products and customers, update order status, prices and stock, and receive a webhook the moment something happens.
Quick start
- In your shop admin, open Settings › Integrations and choose New API key. Pick the permissions the app needs.
- Copy the key. It is shown once; Shopiza only keeps a hash of it.
- Call the API with the key as a bearer token:
curl https://shopiza.io/api/v1/orders?limit=5 \
-H "Authorization: Bearer sz_live_..."
Base URL: https://shopiza.io/api/v1. Machine-readable spec: OpenAPI 3.1.
Authentication
Every request carries one API key in the Authorization: Bearer header (X-API-Key works too). A key belongs to one shop and can only see that shop. Keys are created and revoked by the shop owner or a team admin; revoking takes effect at once and removes the webhooks that key created.
| Scope | What it allows |
|---|---|
orders:read | List and read orders, with items, customer details and addresses. |
orders:write | Change an order status (implies orders:read). |
products:read | List and read products and variants. |
products:write | Change price, sale price, stock and visibility (implies products:read). |
customers:read | List and read customer accounts. |
webhooks:write | Subscribe and unsubscribe webhook URLs through the API. |
A request outside the key’s scopes answers 403 with error.required_scope naming what is missing.
Conventions
- JSON in and out. Send
Content-Type: application/jsonon PATCH and POST. - Money is a decimal string with two places (
"24.90"), in the order’s or product’scurrency. Prices are stored the way the shop enters them (net or gross, per the shop’s pricing setting). - Times are ISO 8601 in UTC (
2026-11-11T10:49:10.000Z). - Lists return
{ "data": [...], "page": 1, "limit": 50, "has_more": true }. Usepageandlimit(1 to 100). Newest first;sort=updated_atorders by last change, which withupdated_aftergives an incremental sync. - Stock is a whole number, or
nullwhen the shop does not track stock for that item. Products with variants keep stock on each variant. - Errors look like
{ "error": { "code": "invalid_field", "message": "...", "field": "price" } }.
| Status | Meaning |
|---|---|
| 400 | A query parameter is invalid (error.param), or the body is not JSON. |
| 401 | No key, or the key is wrong or revoked. |
| 403 | The key lacks a scope, or the shop is not available through the API (suspended or being deleted). |
| 404 | No such object in this shop. |
| 422 | The body has an invalid value (error.field). |
| 429 | Rate limit: 120 requests a minute per key. Wait for the seconds in Retry-After; RateLimit-Remaining shows what is left. |
Endpoints
| Method | Path | Scope and notes |
|---|---|---|
GET | /shop | The shop the key belongs to, and the key’s scopes. Use it to test a key. |
GET | /orders | orders:read Orders, newest first. Filters: status, payment_status, number, email, created_after, updated_after, sort=updated_at. |
GET | /orders/{id} | orders:read One order. |
PATCH | /orders/{id} | orders:write Set status: new, processing, fulfilled, cancelled. |
GET | /products | products:read Products, newest first. Filters: q (name in any language, or SKU), sku, is_active, created_after, updated_after, sort=updated_at. |
GET | /products/{id} | products:read One product with its variants. |
PATCH | /products/{id} | products:write Set price, sale_price, stock, is_active. |
PATCH | /products/{id}/variants/{variantId} | products:write The same four fields on one variant. |
GET | /customers | customers:read Customer accounts, newest first. Filters: email, created_after, updated_after. |
GET | /customers/{id} | customers:read One customer. |
GET | /webhooks | webhooks:write Webhooks this key created. |
POST | /webhooks | webhooks:write Subscribe a URL to events. Returns the signing secret once. |
DELETE | /webhooks/{id} | webhooks:write Unsubscribe. |
The full field lists are in the OpenAPI file. A webhook’s data.object is exactly what the matching GET returns.
Examples
New paid orders since your last sync
curl "https://shopiza.io/api/v1/orders?payment_status=paid&updated_after=2026-11-01T00:00:00Z&sort=updated_at" \
-H "Authorization: Bearer $SHOPIZA_KEY"
Mark an order shipped, with tracking
curl -X PATCH https://shopiza.io/api/v1/orders/1234 \
-H "Authorization: Bearer $SHOPIZA_KEY" -H "Content-Type: application/json" \
-d '{"status":"fulfilled","tracking_number":"JJD000390007","tracking_url":"https://track.example/JJD000390007"}'
Setting fulfilled sends the customer the same “your order is on its way” email as the admin, in the customer’s language. Send "notify_customer": false to skip it. Cancelling restores stock but does not refund: refunds stay in the admin.
Update stock and price of a variant
curl -X PATCH https://shopiza.io/api/v1/products/987/variants/5521 \
-H "Authorization: Bearer $SHOPIZA_KEY" -H "Content-Type: application/json" \
-d '{"stock":14,"price":29.90,"sale_price":null}'
A sale_price must be lower than the price it applies to; null or 0 removes the sale. A variant with "price": null in its response charges the product price.
Webhooks
Add a webhook in Settings › Integrations › Webhooks (or through the API, below). Shopiza sends a POST with a JSON body to your https URL for each event you picked.
| Event | When |
|---|---|
order.created | A customer placed an order (before payment for card orders). |
order.paid | The payment went through, or you marked the order paid. |
order.updated | Any status or payment change. Fires alongside the specific events below. |
order.cancelled | The order was cancelled. |
order.refunded | A full or partial refund was recorded (payment_status tells which). |
product.created | A product was created in the admin, by import or by the AI assistant. |
product.updated | A product was saved in the admin, by import, or through the API. Stock that goes down because of an order does not fire it: use order.created for that. |
product.deleted | A product was deleted. data.object has only id, name, sku and deleted_at. |
customer.created | A shopper created a customer account. |
The body:
{
"id": "6f1c0e5a-2b7d-4e0a-9c3e-8d1f2a3b4c5d",
"type": "order.paid",
"created_at": "2026-11-11T10:49:10.000Z",
"shop_id": 44,
"data": { "object": { "id": 1234, "number": "K7Q2M9", "status": "processing", "payment_status": "paid", "total": "24.90", "...": "..." } }
}
Headers: Shopiza-Event, Shopiza-Event-Id, Shopiza-Delivery-Id, Shopiza-Shop-Id, Shopiza-Signature, and User-Agent: Shopiza-Webhooks/1.0.
- Answer with any 2xx within 10 seconds. Do the slow work after answering.
- Retries: anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 5, 10 and 10 hours: 8 attempts over about 27 hours. Redirects are not followed.
- Duplicates happen (a retry after a timeout you did answer, a manual resend). The event
idis the same each time: use it to ignore repeats. - Order is not guaranteed. Compare
data.object.updated_atwhen it matters. - A dead URL is switched off after 5 deliveries in a row fail all their attempts. The owner sees it on the Integrations page and can switch it back on.
- The payload is a snapshot taken when the event fired. Call the API if you need the current state.
Verifying signatures
Every request is signed with the webhook’s secret (whsec_..., shown once when the webhook is created):
Shopiza-Signature: t=1762858150,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
v1 is the hex HMAC-SHA256 of t, a dot, and the raw request body. Compute it the same way, compare in constant time, and reject timestamps older than five minutes.
// Node.js (Express): use the raw body, not a re-serialised JSON object
const crypto = require('crypto');
app.post('/shopiza-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('Shopiza-Signature') || '';
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', process.env.SHOPIZA_WEBHOOK_SECRET)
.update(parts.t + '.' + req.body.toString('utf8')).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
const ok = fresh && parts.v1 && parts.v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
if (!ok) return res.status(400).end();
const event = JSON.parse(req.body);
res.status(200).end(); // answer first
handle(event); // then do the work
});
# Python (Flask)
import hmac, hashlib, time
from flask import request, abort
parts = dict(p.split('=', 1) for p in request.headers.get('Shopiza-Signature', '').split(','))
expected = hmac.new(SECRET.encode(), (parts['t'] + '.').encode() + request.get_data(), hashlib.sha256).hexdigest()
if abs(time.time() - int(parts['t'])) > 300 or not hmac.compare_digest(parts.get('v1', ''), expected):
abort(400)
AI assistants (MCP)
Shopiza is an MCP server at https://shopiza.io/mcp (Streamable HTTP, stateless). Connect an assistant and ask it things like “what sold best this week”, “which paid orders are not shipped yet” or “set the blue mug to 14 in stock”. It sees only what you allowed, and asks before it changes anything.
claude.ai, ChatGPT and other apps with a “Connect” button: add a custom connector with the URL https://shopiza.io/mcp. The app sends you to Shopiza: sign in, pick the permissions on the consent page and choose Allow. Nothing to copy. You see and disconnect connected apps under Settings › Integrations › Connected apps. Only the shop owner or a team admin can connect an app.
Clients that take a header (Claude Code, Cursor, scripts) can also use an API key from Settings › Integrations:
Tools: get_shop, search_orders, get_order, update_order_status, search_products, get_product, update_product, update_variant, search_customers, sales_summary.
# Claude Code
claude mcp add --transport http shopiza https://shopiza.io/mcp \
--header "Authorization: Bearer sz_live_..."
# Cursor and other clients with an mcp.json
{ "mcpServers": { "shopiza": { "url": "https://shopiza.io/mcp",
"headers": { "Authorization": "Bearer sz_live_..." } } } }
# Claude Desktop (via the mcp-remote bridge)
{ "mcpServers": { "shopiza": { "command": "npx", "args": ["mcp-remote", "https://shopiza.io/mcp",
"--header", "Authorization: Bearer sz_live_..."] } } }
For client developers: OAuth 2.1 with PKCE (S256), discovery through /.well-known/oauth-protected-resource/mcp (RFC 9728) and /.well-known/oauth-authorization-server (RFC 8414), dynamic client registration at /oauth/register (RFC 7591) or a client ID metadata document URL as client_id. Scopes are the API scopes except webhooks:write. Access tokens last an hour; refresh tokens rotate on every use and a reused one ends the connection. Tokens are issued for the resource https://shopiza.io/mcp and do not work on /api/v1.
n8n
Install the Shopiza nodes in n8n under Settings › Community Nodes › Install with the package name n8n-nodes-shopiza (npm). Shopiza Trigger subscribes its own webhook when the workflow is activated and checks every signature; Shopiza reads orders, products and customers and updates order status, prices and stock. The trigger needs an n8n that is reachable over https.
For connector builders
Zapier, Make, n8n and similar tools subscribe through the API instead of the admin. A key with webhooks:write plus the read scope of each event (orders:read for order.* and so on) can:
curl -X POST https://shopiza.io/api/v1/webhooks \
-H "Authorization: Bearer $SHOPIZA_KEY" -H "Content-Type: application/json" \
-d '{"url":"https://hooks.example.com/abc","events":["order.created"]}'
# 201: { "id": 17, "url": "...", "events": ["order.created"], "secret": "whsec_..." }
curl -X DELETE https://shopiza.io/api/v1/webhooks/17 -H "Authorization: Bearer $SHOPIZA_KEY"
A key only sees and removes the webhooks it created. For a polling trigger, list with sort=updated_at and de-duplicate on id. Use GET /shop as the connection test.
Changelog
- 2026-11-12: Sign in with Shopiza (OAuth) for MCP clients such as claude.ai and ChatGPT.
- 2026-11-11: v1. Orders, products, customers, webhooks. MCP server.
Questions or something missing? Write to [email protected].