bagisto-api-admin

---
name: bagisto-api-admin
description: Use when building an admin app or UI on the Bagisto Admin API — a back-office dashboard, an order, catalog, customer, marketing, CMS or settings management screen, an admin mobile app, the Create-Order flow, or any admin panel page on the API. Ask the client's platform and stack first, and treat the api-docs as the source of truth for exact shapes. Trigger phrases include "admin orders", "admin products", "customers", "cart rules", "CMS", "settings", "reporting", "admin panel on the API".
license: MIT
---

# 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.