Skip to main content

​
TeamCopilot API overview

​
Authentication

All API routes require a valid Shopify App Bridge session token. Set the Authorization: Bearer <token> 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

Returns { ok: true, app: "team-ops", release: "<sha>", origin: "<url>" }. No authentication required.

​
Setup

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.
Access: teamManagerAccess. Body: {"intent": "skip_setup"}. Persists setup dismissal per installation generation.

​
Team members

Returns all team members for the shop.
Create a team member. Body: { shopifyStaffGid?, name, email?, phone?, role, hourlyRateCents, pin, defaultLocationGid?, availability? }. PIN must be 4-8 digits. Requires idempotency-key header.
Update a team member. Body: partial fields plus optional pin and status (active/inactive).
Returns active team members with id, name, and default location. Access: teamMemberAccess.

​
Locations

Returns all retail locations.
Upsert a location. Body: { shopifyLocationGid, name, address?, latitude?, longitude?, geofenceMeters?, timezone?, active? }.
Import Shopify locations via Admin GraphQL.

​
Shifts

Returns shifts in the date range (default: past 7 days to next 21 days).
Create a shift. Body: { teamMemberId?, role, locationGid, startsAt, endsAt, breakMinutes?, status?, notes?, laborBudgetCents? }. Detects overlap conflicts (409).
Publish draft shifts. Body: { shiftIds: [...], notify?: boolean }. Sends email/SMS to assigned team members. Returns 207 for partial notification delivery.
Returns role coverage report (shift count, planned hours, labor budget).

​
Shift templates

Body: { name, role, locationGid, startsAt, endsAt, breakMinutes?, targetHeadcount? }.

​
Time clock

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.
Body: { teamMemberId, pin, breakMinutes?, managerNote? }. Rate-limited: 30 requests per 60 seconds per IP.
Returns active team members and recent time entries.
Access: teamManagerAccess. Returns last 200 time entries.
Access: teamManagerAccess, paid. Manager-clock-out for an unresolved entry.

​
Exceptions

Access: teamManagerAccess. Returns unresolved integrity events, missed checklists, and open time entries with missed clock-out detection.
Access: teamManagerAccess, paid. Resolve an integrity event.

​
Checklists

Body: { name, locationGid?, role?, cadence (daily|weekly|per_shift), items: [{ label, requiresPhoto?, sortOrder? }] }.
Body: { templateId, shiftId?, dueAt, locationGid? }.
Body: { teamMemberId, note?, assetBase64? }.

​
Commissions

Body: { name, ruleType (fixed_percent|fixed_amount|goal_bonus), rateBps?, amountCents?, goalThresholdCents?, productQuery?, startsOn?, endsOn?, active? }.
Weekly commission rollup with 7-day window.

​
Billing

​
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

Webhook API version: 2026-04. For the full externally reachable surface, see the source route definitions in src/routes.ts. Pcnaid Documentation › Shopify Ecosystem › TeamCopilot › Developer