bagisto-api-admin

name	bagisto-api-admin
description	ALWAYS use when building an ADMIN app or UI on the Bagisto Admin API — a back-office dashboard, order/catalog/customer/marketing/CMS/settings management screen, an admin mobile app, the Create-Order flow, or ANY admin panel page on the API. Also when the user mentions admin orders, products, customers, cart rules, CMS, settings, reporting, or 'admin panel on the API'. Routes each menu to a reference page; asks the client's platform/stack first; treats the api-docs as the source of truth for exact shapes.
license	MIT
metadata	{"author":"bagisto"}

Build an admin app on the Bagisto Admin API

Implement any admin/back-office interface on the Bagisto Admin API (/api/admin/* REST + POST /api/admin/graphql). The API mirrors the Bagisto admin panel menu-for-menu, so any admin screen can be rebuilt from it. This skill is a router: it gives the flow and points you at the per-menu reference page; the reference pages carry the endpoints, UI/UX, and checklists.

⚠️ Load these FIRST (before any code)

1. reference/connecting-to-the-api.md — admin auth (the Integration Bearer token), the {data,meta} listing envelope, the list→detail→action pattern, permissions, errors, and the verify-before-coding protocol.
2. reference/graphql.md — if the client picked GraphQL: the admin endpoint, the result-field/id rule, camelCase inputs + filter args, cursor pagination.

The api-docs are the source of truth for exact shapes — https://api-docs.bagisto.com (Admin API section) + its /llms.txt index. The reference pages name the endpoints and flow; open the linked docs page for the precise body/response before writing the call. Never invent a payload from memory.

Step 1 — ask the client (CRITICAL, before building)

1. Platform — web, mobile (native/cross-platform), desktop?
2. Framework/stack — React/Next, Vue/Nuxt, Flutter, React Native, plain JS?
3. Which admin menus — Sales, Catalog, Customers, Marketing, CMS, Settings, Configuration, Dashboard/Reporting — or one first?
4. Transport — REST or GraphQL? (REST for list/detail/action screens; GraphQL when a screen needs many related fields in one round-trip. Both fully supported.)
5. First screen/flow — order list + actions, product management, Create-Order, a dashboard, …?

Confirm, then tailor everything to the answers. Don't assume a stack.

The core admin pattern: list → detail → action

Almost every admin screen is the same shape (detailed in connecting-to-the-api.md):

• List — GET /api/admin/<resource> → { data, meta } envelope; drive tables with ?page= + ?per_page= + the screen's filters.
• Detail — GET /api/admin/<resource>/{id} → full record, relations embedded (no follow-up calls).
• Action — POST/PUT/DELETE for create/update/delete + per-record actions (cancel order, create invoice, mass-update, …), each with its own eligibility rules.

Step 2 — open the reference for the menu

Flagship flow

Page	Build this
reference/flows/create-order.md	The admin Create-Order flow (place an order for a customer via a draft cart)

Menus (mirror the admin sidebar)

Page	Covers
reference/menus/sales.md	Orders (list/detail + cancel/comment/invoice/shipment/refund), Invoices, Shipments, Refunds, Transactions, Bookings, CSV exports
reference/menus/catalog.md	Products (datagrid + CRUD + images/inventory/customer-group-prices + mass actions), Categories (+tree), Attributes (+options), Attribute Families
reference/menus/customers.md	Customers (CRUD + addresses/notes/impersonate), Groups, Reviews, GDPR
reference/menus/marketing.md	Cart Rules (+coupons), Catalog Rules, Email Templates, Events, Campaigns, Subscribers, Search Terms/Synonyms, URL Rewrites, Sitemaps
reference/menus/cms.md	CMS Pages
reference/menus/settings.md	Currencies, Channels, Locales, Exchange Rates, Inventory Sources, Tax Rates/Categories, Roles, Users, Themes, Data-Transfer Imports
reference/menus/configuration.md	Store configuration (schema / values / update)
reference/menus/dashboard-reporting.md	Dashboard stats + Reporting (sales/customers/products + export)

Discovery — don't hardcode the nav or permissions

Two read-only endpoints (REST + GraphQL) tell you what the current token can do — drive navigation and action-gating from them instead of hardcoding:

• GET /api/admin/menu (getAdminMenu) — the admin sidebar as a permission-filtered tree; each node maps to its API endpoint (apiResource: { rest, graphql }, or null for group headers / panel-only screens).
• GET /api/admin/permissions (getAdminPermissions) — the token's effective { permissionType, permissions } (["*"] = full access).

Details in reference/connecting-to-the-api.md.

Consolidated critical rules

• Verify before coding. PAUSE → open the endpoint's docs page (or query the MCP) → confirm method/fields → implement → check types.
• Auth: every call sends Authorization: Bearer <id>|<token> (a pre-issued admin Integration token). There's no login endpoint — the token is made in the store's admin panel. The admin GraphQL endpoint is POST /api/admin/graphql (admin token only; not the shop endpoint, no storefront key).
• Permissions: a token is capped by its admin's role — an endpoint the role can't reach returns 403. Build for that.
• Listings are { data, meta } (+ X-Total-* headers); page with ?page=/?per_page= (default 10, cap 50) + the per-screen filters.
• GraphQL action mutations (cancel/invoice/shipment/refund/place-order/cart writes/mass-actions) return result fields, not a generic id; inputs are camelCase; custom filter args are documented per page. See reference/graphql.md.
• Don't hardcode dynamic data (shipping/payment methods in Create-Order, config options) — fetch it.