Managing Agents

Agents are the people in your sales team who use the Soryk app to place orders for B2B customers and earn commissions. Everything about them — name, email, assigned companies, role, territory, language — lives in one place: Admin → Agents.

Create an agent manually

1. Go to Admin → Agents and click Create agent.
2. Fill the modal:
   • Email — unique. Used for login and as the commission attribution key.
   • Name — display name in the app and on payouts.
   • Companies — assign one or more B2B companies (multi-select). Can be edited later.
   • Locale — UI language: EN, IT, ES (the agent app supports more languages, this picks the default).
3. Click Create. The agent is saved as a soryk_agent metaobject. They cannot log in until you send the magic link.

Bulk import via CSV

For teams of 5 or more, use Admin → Agents → Bulk import.

Template columns

Example CSV

email,name,company_ids,locale,role
marco.bianchi@example.com,Marco Bianchi,"gid://shopify/Company/123,gid://shopify/Company/456",it,agent
laura.conti@example.com,Laura Conti,gid://shopify/Company/789,it,manager
sara.romano@example.com,Sara Romano,,en,agent

Invite an agent — magic link

1. Open the agent's profile (Agents → click row).
2. Click Send magic link.
3. Soryk sends an email via Resend with a one-time link. The agent opens it on their phone, gets logged in, and is prompted to install the app from the App Store / Play Store (or use the app in their browser).

Edit a profile

From the agent detail page /agents/[id]:

• Name & email — editable. Changing email re-keys commission attribution from that point forward (past earnings keep their original tag).
• Active toggle — set to inactive to immediately revoke session access without deleting the agent. Useful for suspensions or vacations.
• Locale — switch UI language.
• Companies — add or remove assigned companies.
• Role — agent or manager (see Roles).
• Zone — territory editor (see Territories).

Assign companies to an agent

An agent can be assigned to many companies. A company can have many assigned agents — that's where commission overrides matter (more on the conflict resolution in Commissions → multi-agent fallback).

1. Open the agent profile.
2. In the Companies section, click Add.
3. Search by name. Select one or many. Save.

From the company side: Companies → [Company] → Agents — the same multi-select editor.

Roles & manager hierarchy

Two roles:

• Agent — places orders, builds quotes, sees own commissions and own assigned companies. Cannot see other agents' data.
• Manager — same as agent, plus: sees the team they manage, can place orders on behalf of them, can view team commissions (read-only).

Set up a manager:

1. Toggle the agent's role to Manager.
2. In the Managed agents selector, pick the team members reporting to them.
3. Optionally set a Manager override percent — applied on top of the regular commission for orders the manager personally places.

The setting managerOrderAttribution controls how a manager's order on behalf of a team member is tagged: team_agent (commission goes to the team member) or manager_only (commission goes to the manager).

Territories

Each agent can have a territory definition with five layers:

• Countries — ISO codes (e.g. IT, FR, DE).
• Regions — free-text region names (e.g. Lombardia, Île-de-France).
• ZIP prefixes — e.g. 20 matches all 20xxx postal codes.
• Circles — center lat/lng + radius km (Haversine matching).
• Polygons — array of vertices (ray-casting matching).

Country, region and ZIP work out of the box. Circles + polygons require lat/lng on company locations — see the known caveat.

Full walkthrough: Territories & Geo.

Remove an agent

1. Open the agent profile.
2. Click Delete agent at the bottom.
3. Confirm.

What happens:

• The soryk_agent metaobject is deleted.
• Existing commission earnings are preserved — they stay in the historical record under the deleted agent's email.
• Future orders tagged with that email no longer attribute (the engine logs the unmatched tag).
• Active sessions are revoked on next request.

Best practices