API & Webhooks

Soryk's API is the same one our admin and agent UIs use — there's no separate "public API" to maintain. This page lists what's available and how to call it. For deep integrations or custom workflows, the recommended pattern is: read directly from Shopify metaobjects (your data), use Soryk endpoints only for actions that need server logic (create payment, fix attribution, etc.).

Authentication

Two authentication modes:

Admin endpoints — Shopify session token

Embedded admin requests use the Shopify App Bridge session token. From inside the embedded app you don't need to do anything — App Bridge attaches the token automatically. From outside (rare):

curl -X GET https://your-shop.myshopify.com/apps/soryk/api/admin/agents \
  -H "Authorization: Bearer <session-token>"

Agent + buyer endpoints — JWT cookie

After magic-link or Google SSO sign-in, the JWT is in a HttpOnly secure cookie named soryk_session. Subsequent fetches include it automatically. Don't try to extract or forge it — sessions only work from the actual signed-in browser.

Available endpoints

Admin

Agent

Buyer (when buyerPortalEnabled)

Public

Webhooks

Soryk subscribes to a small set of Shopify webhooks at install time. You don't need to configure anything.

Rate limits

Excess returns 429 with Retry-After.

Examples

Curl — list agents

curl https://your-shop.myshopify.com/apps/soryk/api/admin/agents \
  -H "Authorization: Bearer <session-token>"

Curl — create a commission rule

curl -X POST https://your-shop.myshopify.com/apps/soryk/api/admin/commissions/rules \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Premium wines bonus",
    "scope": "collection",
    "scopeTarget": "gid://shopify/Collection/1234567890",
    "base": "no_tax_no_shipping",
    "ratePercent": 8,
    "priority": 10,
    "deductOnRefund": true
  }'

JavaScript — record a payment

const res = await fetch('/api/admin/commissions/payments', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: 'gid://shopify/Metaobject/...',
    orderIds: ['gid://shopify/Order/1', 'gid://shopify/Order/2'],
    amount: 250.00,
    currency: 'EUR',
    method: 'bank_transfer',
    note: 'April payout',
    paidAt: '2026-04-25'
  })
});

if (res.status === 409) {
  const { duplicateOrderIds, existingPaymentId } = await res.json();
  console.warn('Already paid', duplicateOrderIds, 'in payment', existingPaymentId);
}

Error codes

All error responses follow the same shape:

{
  "code": "INVALID_INPUT",
  "error": "Human-readable message"
}

Standard codes:

The agent UI translates codes via useErrorMessage() — keys live in lib/i18n/agent-dict.ts as error.<CODE> in EN/IT.