Merchio API v1

Tenant-aware, role-based API for Admin, Staff, Operators, and Clients. Authenticate with Bearer tokens, set X-Organisation-Id after selecting an organisation, and use the offline sync endpoints to keep the mobile client up to date.

Quick links: OpenAPI JSON (v3.1) • Swagger UI • Auth header: Authorization: Bearer <token>.

Overview

Merchio API exposes first-class resources for authentication, users, organisations, clients, locations, assignments, inventory, analytics, notifications, approvals, offline sync, and secure media uploads.

Open Interactive Docs

Authentication & Devices

  • POST /v1/auth/register — Create a new account and receive an access token.
  • POST /v1/auth/login — Exchange email + password for an access token.
  • POST /v1/auth/logout — Revoke the current personal access token. Requires auth
  • POST /v1/auth/refresh — Mint a fresh token for the current user. Requires auth
  • POST /v1/auth/password/forgot — Send password reset message (falls back to in-memory mailer when SES SDK is unavailable).
  • POST /v1/auth/password/reset — Reset password with token + new secret.
  • GET /v1/app/bootstrap — Feature flags, enums, minimum supported app version.
  • POST /v1/devices — Register or refresh a device push token.
  • DELETE /v1/devices/{id} — Remove a registered device token.

System & Search

  • GET /v1/time — Current server time (ISO 8601).
  • GET /v1/health — Health/readiness probe.
  • GET /v1/version — API + application version metadata.
  • POST /v1/feedback — Submit feedback or an issue (stored as an audit trail event).
  • GET /v1/search — Search clients, locations, and products.
  • GET /v1/search/suggestions — Lightweight typeahead suggestions.

User Profile & Notifications

  • GET /v1/users/me — Authenticated user profile, memberships, avatar URLs.
  • PATCH /v1/users/me — Update personal details and avatar (use the avatar field as base64 or multipart upload).
  • DELETE /v1/users/me — Deactivate the account (marks status as inactive, revokes tokens, and can be reversed by logging in again).
  • PATCH /v1/users/me/password — Change password (requires current password).
  • GET /v1/users/me/organisations — Organisation memberships with roles and role permissions.
  • POST /v1/users/me/location — Record the latest GPS fix (accepts optional accuracy + meta) and append to the user’s location history.
  • POST /v1/users/me/location/ip — Resolve approximate location via IP lookup and log a history entry with the provider metadata.
  • GET /v1/notifications — Notification feed.
  • PATCH /v1/notifications/{id}/read — Mark a single notification as read.
  • PATCH /v1/notifications/read-all — Mark all notifications as read.

Organisations & Admin

  • GET /v1/organisations/{id} — Organisation profile plus KPIs.
  • PATCH /v1/organisations/{id} — Update organisation details and logo.
  • GET /v1/settings — Aggregated settings (global/org/user scopes).
  • PATCH /v1/settings — Upsert settings for the requested scope.
  • GET /v1/admin/users — List organisation members with roles (comma-separated filters for ids, role, and status).
  • POST /v1/admin/users — Create or attach a user to the organisation.
  • PATCH /v1/admin/users/{id} — Update member role or status.
  • GET /v1/admin/members — Membership directory with search, role, and status filters.
  • GET /v1/admin/operators — Operator KYC profiles with verification filters (comma-separated filters for ids and verification_status).
  • GET /v1/admin/roles — Role catalogue for role-based UI.
  • GET /v1/admin/invitations — Pending invitations.
  • POST /v1/admin/invitations — Invite by email.
  • PATCH /v1/admin/invitations/{id}/cancel — Cancel invitation.

Clients & Client Users

  • GET /v1/clients — List clients with filters and location counts (supports comma-separated ids filters).
  • POST /v1/clients — Create a client record.
  • GET /v1/clients/{id} — Client detail including assignments.
  • PATCH /v1/clients/{id} — Update client attributes (brand, contact, status).
  • GET /v1/clients/{id}/users — List client-facing members.
  • POST /v1/clients/{id}/users — Attach a user to the client.
  • DELETE /v1/clients/{id}/users/{userId} — Remove a client membership.

Locations & Assignments

  • GET /v1/locations — Paged locations (comma-separated filters for ids, brand, city, state, and status).
  • POST /v1/locations — Create a location.
  • GET /v1/locations/{id} — Location detail with recent client assignments.
  • PATCH /v1/locations/{id} — Update location details, geodata, contact info.
  • GET /v1/client-locations — List client/location pairings with visit data (comma-separated filters for ids, client_id, location_id, operator_id, status — use unassigned, assigned, scheduled, in_progress, completed, reviewed, failed, or all — plus location_brand, location_city, location_state, next_visit_from, next_visit_until, or next_visit_at[start_date|end_date]).
  • GET /v1/client-locations/assigned — Operator’s active assignments.
  • GET /v1/client-locations/{id} — Detailed assignment with client, location, operator, and recent histories.
  • GET /v1/client-locations/{id}/histories — Activities recorded for a specific client-location.
  • PATCH /v1/client-locations/{id}/schedule — Update next visit date.
  • POST /v1/client-locations/{id}/assign — Assign or reassign an operator (expects a ULID string for operator_id).
  • POST /v1/client-locations/{id}/status — Transition workflow status (only the assigned operator may update).
  • GET /v1/operations/compliance — Operations Compliance list with text search plus filters for status, workflow_category_id, client_id, location_id, operator_id, supervisor_id, city/state, and submitted_from/submitted_until; includes completion percentages and location/client context.
  • GET /v1/operator/assignments — Assignment history.
  • POST /v1/operator/assignments — Create assignment record.
  • PATCH /v1/operator/assignments/{id} — Update/cancel assignment.

Products & Inventory

  • GET /v1/products — List products (comma-separated filters for ids, client_id, category_id, and status, plus search).
  • POST /v1/products — Create a product.
  • GET /v1/products/{id} — Product detail.
  • PATCH /v1/products/{id} — Update product metadata.
  • PATCH /v1/products/{id}/publish — Publish/unpublish a product.
  • GET /v1/categories — Category catalogue.
  • GET /v1/tags — Tag catalogue.
  • GET /v1/client-locations/{id}/products — Inventory items at a client location.
  • POST /v1/client-locations/{id}/products/create — Create a single inventory batch (separate stock per expiry date).
  • PATCH /v1/client-locations/{id}/products/{productId} — Update balances, expiry, remark.
  • POST /v1/client-locations/{id}/products/bulk — Bulk add/update inventory rows (use expiry_date to create separate batches; include id to update a specific row).
  • POST /v1/client-locations/{id}/products/{productId}/adjustments — Record a stock adjustment delta.

Admin Client Location Tools

  • GET /v1/admin/client-location-products — Inventory list with client/location/operator filters.
  • PATCH /v1/admin/client-location-products/{clientLocationProduct} — Update stock, expiry, pricing, or status.
  • POST /v1/admin/client-location-products/bulk — Bulk upsert assignments (supports multiple batches via expiry_date; send id to update) and report per-item outcome.
  • POST /v1/admin/client-location-products/{clientLocationProduct}/adjust — Apply a stock delta with optional remark/images.
  • GET /v1/admin/client-location-histories — Search activities by client, location, operator, status, brand, city, state, and date range and receive any captured inventories snapshots.
  • POST /v1/admin/client-location-histories — Create a history entry on behalf of an operator.
  • GET /v1/admin/client-location-histories/{id} — Retrieve activity detail with full context, including inventories when available.
  • PATCH /v1/admin/client-location-histories/{id}/review — Mark an activity as reviewed.

Operator Profile & Media

  • GET /v1/operator/profile — Operator KYC status, rating, document metadata.
  • PATCH /v1/operator/profile — Update KYC data and notes.
  • POST /v1/operator/profile/documents/presign — Presign operator document uploads.
  • POST /v1/operator/profile/documents/complete — Confirm uploaded documents.
  • POST /v1/histories/photos/presign — Presign history photo uploads.
  • POST /v1/histories/photos/complete — Attach uploaded history photos.

Analytics, Approvals & Sync

  • GET /v1/analytics/overview — Permission-aware dashboard cards (requires dashboard.view); the cards array surfaces Clients, Locations, Products, Operators, and Total Users when the caller holds the matching administration permissions, and status_cards mirrors the operations status buckets.
  • GET /v1/analytics/operations — Operations workload snapshot (requires operations.client_locations.view); cards include visits_due_now, completed_due_again, and the same status buckets surfaced again for quick access, while status_cards remains the canonical list for unassigned, assigned, scheduled, in_progress, completed, reviewed, failed, and all.
  • GET /v1/analytics/trends/client-locations — Monthly client location growth trends.
  • GET /v1/analytics/trends/activities — Monthly activity status trends.
  • GET /v1/analytics/trends/products — Monthly product lifecycle trends.
  • GET /v1/analytics/operator/overview — Operator assignment counters.
  • GET /v1/analytics/operator/trends — Daily trend data for operators.
  • GET /v1/approvals — Approval queue (filter by status/type).
  • POST /v1/approvals — Create approval request.
  • PATCH /v1/approvals/{id} — Update approval decision or remark.
  • GET /v1/sync/bootstrap — Initial sync slices + cursor.
  • GET /v1/sync/changes — Incremental changes since cursor.
  • POST /v1/sync/push — Push offline operations (eg. histories, inventory adjustments).

Developer Tips