API keys and webhooks

Pro and Advanced plans (and the free trial in test mode: keys start with so_test_, 30 requests a minute instead of 120). Needs the Developers or Settings staff area (owners and admins always). Full reference: sellorchard.com/docs/api (also GET https://api.sellorchard.com/v1/openapi.json).

1. Settings → Developers → API keys → Create key: name it, tick the scopes it needs (read / write per resource: products, inventory, orders, customers, discounts, gift cards, bookings; read reports and store; write includes read) and optionally an expiry date. The secret (so_live_…) is shown once — copy it into your integration. Send it as Authorization: Bearer so_live_… to https://api.sellorchard.com/v1/. The list shows each key's prefix…last 4 characters, scopes, last used and who created it. Roll makes a new secret (the old one stops working at once); Revoke switches the key off for good. Edit a key's name or scopes any time.
2. What the API covers: store details, products (with variants, options, images imported from URLs), categories and brands, locations and stock per location (adjust / set), orders (list, create — priced by the catalogue or given prices, paid or pending, optional receipt email — fulfil with tracking, cancel, refund, notes, tags), customers, discount codes, gift cards (issue — the code is shown once — and disable), bookings (list, cancel), purchase orders and the sales report. Lists use cursor pagination (limit up to 250, cursor from next_cursor) and updated_since / created_since. Changes made through the API appear in Settings → Activity as "… via API key {name}" and send the same emails as changes in the admin.
3. Limits and errors: 120 requests a minute per key (headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; over the limit you get 429 with Retry-After). Errors look like {"error": {"type": "invalid_request", "message": "…", "param": "…"}}. Send an Idempotency-Key header on POST requests so retries never create things twice (kept 24 hours).
4. Webhooks → Add endpoint: an https:// URL (private / local addresses aren't allowed), a description, the topics (order created / updated / paid / fulfilled / cancelled / refunded, product created / updated / deleted, inventory updated, customer created / updated, booking created / updated / cancelled, refund created, return created / updated, discount created, gift card issued) and active on/off. The signing secret (whsec_…) is shown once; Roll secret makes a new one. Each request is a JSON POST with X-SellOrchard-Topic, X-SellOrchard-Webhook-Id (the event id, use it to ignore duplicates) and X-SellOrchard-Signature: t=…,v1=… — the HMAC-SHA256 of "{t}.{raw body}" with the whole secret as the key. Answer with any 2xx within 10 seconds.
5. Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours (8 tries). An endpoint that keeps failing for 3 days is switched off and the store owner gets an email; fix the URL and switch it back on. Each endpoint shows healthy / failing / disabled and its Deliveries (status, topic, response code, attempts, duration; open one to see the request and response, Resend it). Send test sends a sample event for a topic and shows the answer. Deliveries are kept 30 days; the API logs tab (filter by key and status) keeps 14 days.