Soryk Sales does not expose a public REST API you can call from your own code. It is a Shopify app with a few authenticated surfaces and a set of Shopify webhooks it subscribes to. This page explains how each surface proves who it is, which webhook topics Soryk verifies and acts on, the error shape you will see in responses, and the environment keys that matter for custom or self-hosted installs.
How each surface authenticates
Soryk has several request surfaces, and each one authenticates differently depending on who is calling it.
| Surface | Auth |
|---|---|
| Admin routes | Verify the Shopify session token. These are the embedded admin surfaces you use inside Shopify. |
| Agent routes | Verify a signed JWT agent session, issued after an agent signs in. |
| Customer routes | Verify a JWT scoped to the shop and company, so a buyer only ever reaches their own store and company data. |
| Public quote endpoints | Authenticate with a token in the URL, so a recipient can open a shared quote without signing in. |
Webhooks
Soryk subscribes to and verifies a set of Shopify webhooks. Every one is verified with HMAC-SHA256 using the app secret, so a request that does not carry a valid signature is rejected before it is processed.
| Topic | What it does |
|---|---|
app/uninstalled | Cleanup. Removes the data Soryk keeps for the shop when the app is uninstalled. |
refunds/create | Raises a commission refund alert. The handler is idempotent per order and payment, and it refreshes the analytics cache. |
orders/create | Processes a newly created order. |
customers/data_request | GDPR topic. Handles a customer data request. |
customers/redact | GDPR topic. Handles a customer redaction request. |
shop/redact | GDPR topic. Handles a shop redaction request. |
Error format
API responses use a machine-readable error shape with a code and a message, so your integration can branch on the code rather than parsing prose.
{"code":"PLAN_UPGRADE_REQUIRED","error":"This feature needs the Growth plan"}Common codes you may encounter:
NOT_AUTHENTICATED: the request carried no valid session or token.FORBIDDEN: authenticated, but not allowed to perform this action.RATE_LIMITED: too many requests in a short window.PLAN_UPGRADE_REQUIRED: the feature is gated behind a higher plan.PLAN_AGENT_LIMIT: the current plan's agent limit has been reached.AGENT_DISABLED: the agent account is disabled.QUOTE_DUPLICATE_ORDER: the quote has already produced an order.EMAIL_NOT_DELIVERED: a transactional email could not be delivered.
Integration keys
For custom or self-hosted installs, these are the notable environment keys. On the hosted app they are already configured for you.
| Key | Purpose |
|---|---|
RESEND_API_KEY | Transactional email (magic links, quote sends). |
ANTHROPIC_API_KEY | Territory AI audit. |
| VAPID keys | Web push notifications. |
| Google OAuth credentials | Agent and buyer sign-in with Google. |
| Microsoft OAuth credentials | Agent and buyer sign-in with Microsoft. |
| Upstash / KV Redis credentials | Cache, tokens and rate-limit state. |
SORYK_DISTRIBUTION | Billing distribution mode for the install. |
SORYK_FORCE_PLAN | Plan override for custom installs. |
Most merchants never touch these keys. On the hosted app they are handled for you, and you can run Soryk without ever opening an environment file.