Skip to main content

​
TeamCopilot quickstart

​
What is TeamCopilot?

TeamCopilot is a Shopify POS team operations app for scheduling, time-clock integrity, checklists, exception handling, and commission summaries. It runs as an embedded Shopify admin app on Cloudflare Workers with a PostgreSQL database.

​
Shopify app scopes

Defined in shopify.app.toml:
  • read_orders — Commission attribution from paid orders
  • read_locations — Location sync from Shopify Admin
The app requests an expiring offline credential at installation and verifies granted scopes match the configured set.

​
POS extension

One POS UI extension is included:
  • pos-time-clock — Targets pos.home.tile.render (Tile.tsx: Team Clock heading) and pos.home.modal.render (Modal.tsx: clock-in/clock-out form with member ID and PIN fields). Uses Preact and @shopify/ui-extensions API 2026-04.

​
Sign-in model

  1. Shopify OAuth install flow at /auth/*.
  2. App Bridge ID-token verification for every embedded page view.
  3. Session token exchange for API authorization.
  4. Role-based access via shop_staff_access PostgreSQL table: member, manager, admin.
  5. The first unassigned Shopify account owner becomes an app administrator automatically.

​
Public integration points

  • REST API (embedded admin routes under /api/*) — see the API overview
  • Webhooks — POST /webhooks/shopify accepts app lifecycle, billing, order attribution, and GDPR compliance topics
  • Health endpoint — GET /health returns release SHA and origin
  • POS time-clock extension — calls POST /api/time-clock/clock-in and POST /api/time-clock/clock-out

​
Next steps

Pcnaid Documentation › Shopify Ecosystem › TeamCopilot › Developer