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

  1. In your shop admin, open Settings › Integrations and choose New API key. Pick the permissions the app needs.
  2. Copy the key. It is shown once; Shopiza only keeps a hash of it.
  3. 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.

ScopeWhat it allows
orders:readList and read orders, with items, customer details and addresses.
orders:writeChange an order status (implies orders:read).
products:readList and read products and variants.
products:writeChange price, sale price, stock and visibility (implies products:read).
customers:readList and read customer accounts.
webhooks:writeSubscribe 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/json on PATCH and POST.
  • Money is a decimal string with two places ("24.90"), in the order’s or product’s currency. 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 }. Use page and limit (1 to 100). Newest first; sort=updated_at orders by last change, which with updated_after gives an incremental sync.
  • Stock is a whole number, or null when 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" } }.
StatusMeaning
400A query parameter is invalid (error.param), or the body is not JSON.
401No key, or the key is wrong or revoked.
403The key lacks a scope, or the shop is not available through the API (suspended or being deleted).
404No such object in this shop.
422The body has an invalid value (error.field).
429Rate limit: 120 requests a minute per key. Wait for the seconds in Retry-After; RateLimit-Remaining shows what is left.

Endpoints

MethodPathScope and notes
GET/shopThe shop the key belongs to, and the key’s scopes. Use it to test a key.
GET/ordersorders: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/productsproducts: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/customerscustomers:read Customer accounts, newest first. Filters: email, created_after, updated_after.
GET/customers/{id}customers:read One customer.
GET/webhookswebhooks:write Webhooks this key created.
POST/webhookswebhooks: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.

EventWhen
order.createdA customer placed an order (before payment for card orders).
order.paidThe payment went through, or you marked the order paid.
order.updatedAny status or payment change. Fires alongside the specific events below.
order.cancelledThe order was cancelled.
order.refundedA full or partial refund was recorded (payment_status tells which).
product.createdA product was created in the admin, by import or by the AI assistant.
product.updatedA 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.deletedA product was deleted. data.object has only id, name, sku and deleted_at.
customer.createdA 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 id is the same each time: use it to ignore repeats.
  • Order is not guaranteed. Compare data.object.updated_at when 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].