> ## Documentation Index > Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt > Use this file to discover all available pages before exploring further. # TeamCopilot API overview > REST API reference for the TeamCopilot embedded admin — team members, shifts, time clock, checklists, commissions, and settings. # TeamCopilot API overview ## Authentication All API routes require a valid Shopify App Bridge session token. Set the `Authorization: Bearer ` header. Token exchange is handled by the `requireShopSession()` middleware. Route-level authorization uses `teamMemberAccess`, `teamManagerAccess`, or `teamAdminAccess` middleware backed by `shop_staff_access`. Paid API routes require an active subscription and use `requireFreshShopEntitlement()` middleware. ## Health check ```bash theme={null} curl --fail-with-body --silent --show-error https://teamcopilot.shpfy.pndsvcs.com/health ``` Returns `{ ok: true, app: "team-ops", release: "", origin: "" }`. No authentication required. ## Setup ``` GET /api/setup-status ``` **Access:** teamManagerAccess. Returns the 4-step onboarding status: billing, location, team\_member, shift\_template. Each step has `key`, `title`, `description`, `href`, `complete`, and `blocked` properties. ``` POST /api/setup/skip ``` **Access:** teamManagerAccess. Body: `{"intent": "skip_setup"}`. Persists setup dismissal per installation generation. ## Team members ``` GET /api/team-members ``` Returns all team members for the shop. ``` POST /api/team-members ``` Create a team member. Body: `{ shopifyStaffGid?, name, email?, phone?, role, hourlyRateCents, pin, defaultLocationGid?, availability? }`. PIN must be 4-8 digits. Requires idempotency-key header. ``` PATCH /api/team-members/:id ``` Update a team member. Body: partial fields plus optional `pin` and `status` (active/inactive). ``` GET /api/team-directory ``` Returns active team members with id, name, and default location. Access: teamMemberAccess. ## Locations ``` GET /api/locations ``` Returns all retail locations. ``` POST /api/locations ``` Upsert a location. Body: `{ shopifyLocationGid, name, address?, latitude?, longitude?, geofenceMeters?, timezone?, active? }`. ``` POST /api/locations/sync-shopify ``` Import Shopify locations via Admin GraphQL. ## Shifts ``` GET /api/shifts?start=&end= ``` Returns shifts in the date range (default: past 7 days to next 21 days). ``` POST /api/shifts ``` Create a shift. Body: `{ teamMemberId?, role, locationGid, startsAt, endsAt, breakMinutes?, status?, notes?, laborBudgetCents? }`. Detects overlap conflicts (409). ``` POST /api/shifts/publish ``` Publish draft shifts. Body: `{ shiftIds: [...], notify?: boolean }`. Sends email/SMS to assigned team members. Returns 207 for partial notification delivery. ``` GET /api/schedule-summary?start=&end= ``` Returns role coverage report (shift count, planned hours, labor budget). ## Shift templates ``` GET /api/shift-templates ``` ``` POST /api/shift-templates ``` Body: `{ name, role, locationGid, startsAt, endsAt, breakMinutes?, targetHeadcount? }`. ``` DELETE /api/shift-templates/:id ``` ## Time clock ``` POST /api/time-clock/clock-in ``` **Access:** teamMemberAccess, paid. Body: `{ teamMemberId, pin, shiftId?, locationGid?, latitude?, longitude?, deviceFingerprint? }`. Returns time entry and integrity evaluation. Rate-limited: 30 requests per 60 seconds per IP. ``` POST /api/time-clock/clock-out ``` Body: `{ teamMemberId, pin, breakMinutes?, managerNote? }`. Rate-limited: 30 requests per 60 seconds per IP. ``` GET /api/time-clock/status ``` Returns active team members and recent time entries. ``` GET /api/time-entries ``` **Access:** teamManagerAccess. Returns last 200 time entries. ``` POST /api/time-entries/:id/manager-clock-out ``` **Access:** teamManagerAccess, paid. Manager-clock-out for an unresolved entry. ## Exceptions ``` GET /api/exceptions ``` **Access:** teamManagerAccess. Returns unresolved integrity events, missed checklists, and open time entries with missed clock-out detection. ``` POST /api/exceptions/:id/resolve ``` **Access:** teamManagerAccess, paid. Resolve an integrity event. ## Checklists ``` GET /api/checklist-templates ``` ``` POST /api/checklist-templates ``` Body: `{ name, locationGid?, role?, cadence (daily|weekly|per_shift), items: [{ label, requiresPhoto?, sortOrder? }] }`. ``` GET /api/checklist-runs ``` ``` POST /api/checklist-runs ``` Body: `{ templateId, shiftId?, dueAt, locationGid? }`. ``` POST /api/checklist-runs/:runId/items/:itemId/complete ``` Body: `{ teamMemberId, note?, assetBase64? }`. ## Commissions ``` GET /api/commission-rules ``` ``` POST /api/commission-rules ``` Body: `{ name, ruleType (fixed_percent|fixed_amount|goal_bonus), rateBps?, amountCents?, goalThresholdCents?, productQuery?, startsOn?, endsOn?, active? }`. ``` GET /api/commission-summary?start= ``` Weekly commission rollup with 7-day window. ## Billing ``` POST /billing/subscribe ``` ``` POST /billing/change ``` ``` POST /billing/cancel ``` ``` GET /billing/status ``` ## POS extension The POS time-clock extension targets `pos.home.tile.render` (Tile.tsx) and `pos.home.modal.render` (Modal.tsx). It calls `POST /api/time-clock/clock-in` and `POST /api/time-clock/clock-out` with a bearer token from `shopify.session.getSessionToken()`. Request timeout: 15 seconds. ## Webhooks | Topic | Endpoint | Purpose | | - | - | - | | `app/uninstalled` | `POST /webhooks/shopify` | Clears access credentials | | `app_subscriptions/update` | `POST /webhooks/shopify` | Billing state changes | | `orders/paid` | `POST /webhooks/shopify` | Commission attribution | | `shop/update` | `POST /webhooks/shopify` | Shop data refresh | | `customers/data_request` | `POST /webhooks/shopify` | Privacy export (GDPR) | | `customers/redact` | `POST /webhooks/shopify` | Customer data erasure | | `shop/redact` | `POST /webhooks/shopify` | Full tenant erasure | Webhook API version: `2026-04`. For the full externally reachable surface, see the source route definitions in `src/routes.ts`. [Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [TeamCopilot](https://docs.pcnaid.com/nodes/shopify/teamcopilot/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/teamcopilot/developer/index) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.