Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Consolidate admin plans into docs/plans/

Damian Legawiec0e656232e4e6
diff --git a/CLAUDE.md b/CLAUDE.md
index fc698b1bf8..c16a66e822 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,7 +13,8 @@ Use `/project:create-plan` and `/project:update-plan` for plan management.
Current plans:
- `6.0-cart-order-split.md` — Cart/Order model separation, polymorphic LineItem
-- `6.0-admin-spa.md` — React admin architecture, plugin system
+- `6.0-admin-api.md` — Admin REST API conventions, auth, endpoint list (~300 endpoints)
+- `6.0-admin-spa.md` — React admin architecture, extension points, table registry
- `6.0-product-types.md` — Prototype → ProductType rename, MetafieldDefinition schema enforcement
- `6.0-remove-master-variant.md` — Eliminate is_master, add default_variant_id FK on Product
- `6.0-split-adjustments.md` — Replace polymorphic Adjustment with TaxLine, Discount, Fee
diff --git a/docs/plans/6.0-admin-api.md b/docs/plans/6.0-admin-api.md
new file mode 100644
index 0000000000..6fa0eb22a4
--- /dev/null
+++ b/docs/plans/6.0-admin-api.md
@@ -0,0 +1,818 @@
+# Admin API
+
+**Status:** In Progress
+**Target:** Spree 6.0
+**Depends on:** `6.0-admin-spa.md`, `6.0-platform-auth.md`
+**Author:** damian
+**Last updated:** 2026-04-11
+
+## Summary
+
+A new REST API namespace (`/api/v3/admin/*`) that exposes every admin resource and operation currently served by the `spree/admin` Rails engine. Provides the programmatic backbone for the new React admin SPA, the TypeScript SDK, the CLI, and any other admin-facing tooling. Follows the same conventions as the Store API (flat JSON, prefixed IDs, Ransack filters, Pagy pagination, CanCanCan authorization) with a separate JWT audience and admin-scoped authentication.
+
+## Key Decisions (do not deviate without discussion)
+
+- **All controllers inherit from `Spree::Api::V3::Admin::ResourceController`** — no bespoke controllers unless absolutely necessary.
+- **RESTful only** — `POST` to create, `PATCH` to update, `DELETE` to destroy. No custom verbs except for state-machine actions (`/cancel`, `/approve`, etc.).
+- **Admin serializers extend Store API serializers** — inherit the public fields and add admin-only ones. Never duplicate attribute definitions.
+- **Flat JSON for nested resources** — no Rails nested attributes. Target audience is TypeScript developers, not Rails devs.
+- **Prefixed IDs everywhere** — requests and responses. Including association IDs.
+- **Separate JWT audience (`admin_api`)** — admin tokens MUST NOT be valid on the Store API and vice versa. Uses `Spree.admin_user_class`.
+- **Two auth mechanisms, both already infrastructured:**
+ 1. Secret API keys (`spree_sk_xxx`) via `Authorization: Bearer` for server-to-server
+ 2. JWT tokens via `Authorization: Bearer` for SPA sessions
+- **Stripe-style error responses** — same format as Store API (see `docs/api-reference/store-api/errors.mdx`).
+- **Use existing services for business logic** — cart create, order update, line item CRUD, etc. Only create new services when direct `record.update!` would embed non-trivial business rules in the controller.
+- **Max 2 levels of nesting** — e.g., `/orders/:id/line_items/:id` is fine, `/orders/:id/shipments/:id/rates/:id` is not. Flatten with filter params when necessary.
+- **Attachments via multipart/form-data** — ActiveStorage underneath. Product images use `Spree::Asset` (ActiveStorage + alt text + ordering + variant scoping).
+- **Typelizer generates TypeScript types after every serializer change** — part of the PR checklist; never merge a serializer change without regenerating.
+
+## Design Details
+
+### Controller hierarchy
+
+```
+Spree::Api::V3::BaseController # shared concerns: pagination, Ransack, caching
+ └── Spree::Api::V3::Admin::BaseController
+ └── Spree::Api::V3::Admin::ResourceController # default CRUD
+ └── Spree::Api::V3::Admin::ProductsController
+ └── Spree::Api::V3::Admin::OrdersController
+ └── ...
+```
+
+`ResourceController` provides a default `index`/`show`/`create`/`update`/`destroy` implementation. Subclasses override `model_class`, `serializer_class`, and optionally `scope`, `permitted_params`, `find_resource`, `scope_includes`. Most admin controllers should fit in 30–80 lines.
+
+### Authentication
+
+- `Spree::Api::V3::AdminAuthentication` concern added to `Admin::BaseController`
+- Tries secret API key first, falls back to JWT with admin audience
+- Refresh tokens via `Spree::RefreshToken` — rotated on every refresh
+- `/auth/login`, `/auth/refresh` live on `Admin::AuthController` which skips `authenticate_admin!`
+- Returns `{ token, refresh_token, user }` shape
+
+### Response format
+
+- Flat JSON, no root key wrapping (`{ id: ..., name: ... }` not `{ product: { id: ... } }`)
+- Collections return `{ data: [...], meta: { total_count, page, pages, limit } }`
+- Prefixed IDs everywhere (`prod_86Rf07xd4z`, `variant_k5nR8xLq`)
+- `?expand=variants,variants.prices` to include associations (max 4 levels)
+- `?q[name_cont]=shirt` for Ransack filtering
+- `?sort=-created_at` for sorting (JSON:API convention)
+
+### Example: product create/update
+
+```json
+{
+ "name": "Test product",
+ "tax_category_id": "taxcat_abc1234",
+ "taxon_ids": ["taxon_abc123", "taxon_def456"],
+ "tags": ["eco", "best-seller"],
+ "variants": [
+ {
+ "option_type": "size",
+ "option_value": "small",
+ "total_on_hand": 10,
+ "track_inventory": true,
+ "width": 10.5,
+ "height": 5.2,
+ "depth": 2.1,
+ "weight": 0.5,
+ "dimensions_unit": "cm",
+ "weight_unit": "kg",
+ "prices": [
+ { "currency": "USD", "amount": 10.99 },
+ { "currency": "EUR", "amount": 9.99 }
+ ]
+ }
+ ]
+}
+```
+
+Validation errors return `422` with:
+
+```json
+{
+ "error": {
+ "code": "validation_error",
+ "message": "Name can't be blank",
+ "details": { "name": ["can't be blank"] }
+ }
+}
+```
+
+### Example: order create with line items (one call)
+
+```json
+{
+ "currency": "USD",
+ "locale": "en-US",
+ "line_items": [
+ { "variant_id": "variant_123456789", "quantity": 1 },
+ { "variant_id": "variant_987654321", "quantity": 2 }
+ ]
+}
+```
+
+### Permissions / `GET /me`
+
+`GET /api/v3/admin/me` returns the current admin user plus a serialized list of their permissions (CanCanCan rules flattened). The SPA consumes this to drive UI permission checks; the server still enforces `authorize!` on every action.
+
+```json
+{
+ "user": { "id": "admin_xxx", "email": "...", ... },
+ "permissions": [
+ { "allow": true, "actions": ["manage"], "subjects": ["all"], "has_conditions": false },
+ { "allow": false, "actions": ["destroy"], "subjects": ["Spree::Order"], "has_conditions": true }
+ ]
+}
+```
+
+Per-record conditions (CanCanCan blocks/hashes) are not serialized — only `has_conditions: true` as a hint. The SPA shows actions optimistically and handles 403 from the API.
+
+### Testing
+
+- Controller specs first; save integration/rswag specs for after the design solidifies per endpoint.
+- Serializer specs for attribute coverage — keep controller specs focused on behavior, not field-by-field assertions.
+- Lean and pragmatic. Cover known edge cases, skip trivial validations.
+
+## Migration Path
+
+### Infrastructure (done)
+
+- Base controllers, resource controller, admin authentication, JWT with admin audience, secret API key auth, prefixed IDs, error handling, Pagy, Ransack, CanCanCan scoping — all in place.
+- Initial admin serializers exist for Product, Variant, Order, Customer, Price, Metafield, Taxon, Taxonomy, LineItem. More are added as endpoints come online.
+
+### Endpoint rollout order
+
+1. **Authentication** — login, refresh, me ✅
+2. **Products + Variants + Assets + Options** — highest-priority, hardest, nested
+3. **Orders + Line Items + Shipments + Payments + Adjustments + Refunds**
+4. **Customers + Addresses + Store Credits + Gift Cards**
+5. **Promotions + Rules + Actions**
+6. **Stock + Stock Transfers + Price Lists**
+7. **Taxonomy + Classifications**
+8. **Store settings, Policies, Admin users, Roles, Invitations**
+9. **Metafields / Custom Fields + Translations (polymorphic)**
+10. **Webhooks, API keys, Integrations**
+11. **Reports, Exports, Imports, Dashboard analytics**
+
+### PR process for each endpoint
+
+1. Add controller and route
+2. Add/extend admin serializer
+3. Run `bundle exec rake typelizer:generate` + `pnpm generate:zod`
+4. Add controller spec (+ serializer spec if new attributes)
+5. Add SDK resource in `@spree/admin-sdk`
+6. Mark endpoint `[x]` in this plan
+7. If public-facing: update OpenAPI spec with `bundle exec rake rswag:specs:swaggerize`
+
+## Constraints on Current Work
+
+- Never add endpoints outside `Admin::ResourceController` hierarchy without a written exception in this plan.
+- Never expose raw IDs — always prefixed.
+- Never use Rails nested attributes in the API layer.
+- Never duplicate a Store serializer — extend it instead.
+- Never merge a serializer change without running Typelizer.
+- Never create new services unless absolutely necessary; `record.update` is almost always enough.
+
+## Changes from 5.x to 6.0
+
+This plan reflects the 6.0 model/naming landscape. Endpoints removed from 5.x or renamed are tracked in the [Removed / Renamed endpoints](#removed--renamed-endpoints) table at the top so contributors don't accidentally re-implement them.
+
+### Removed / renamed endpoints
+
+| 5.x endpoint | 6.0 endpoint | Reason |
+|---|---|---|
+| `/api/v3/admin/taxonomies/*` | **removed** | `Spree::Taxonomy` dropped; `Category` belongs directly to store. See `6.0-replace-taxons-with-categories.md` |
+| `/api/v3/admin/taxons/*` | `/api/v3/admin/categories/*` | `Spree::Taxon` → `Spree::Category` rename |
+| `/api/v3/admin/shipping_methods/*` | `/api/v3/admin/delivery_methods/*` | `ShippingMethod` → `DeliveryMethod` rename |
+| `/api/v3/admin/orders/:id/shipments/*` | `/api/v3/admin/orders/:id/fulfillments/*` | `Shipment` → `Fulfillment` rename |
+| `/api/v3/admin/shipping_categories/*` | **removed** | Replaced by `ProductType.fulfillment_types`. See `6.0-fulfillment-and-delivery.md` |
+| `/api/v3/admin/zones/*` | **removed** | Tax zones → direct country/state FKs on `TaxRate`. Shipping zones → new `DeliveryZone`. See `6.0-tax-provider.md`, `6.0-fulfillment-and-delivery.md` |
+| `/api/v3/admin/return_authorizations/*` | `/api/v3/admin/returns/*` | `ReturnAuthorization` → `Return`. See `6.0-returns-exchanges-claims.md` |
+| `/api/v3/admin/customer_returns/*` | **removed** | Merged into `Return` + `ReturnItem` |
+| `/api/v3/admin/orders/:id/reimbursements/*` | **removed** | Replaced by direct `Refund` on Returns/Exchanges/Claims |
+| `/api/v3/admin/reimbursement_types/*` | **removed** | Concept dropped |
+| `/api/v3/admin/prototypes/*` | `/api/v3/admin/product_types/*` | `Prototype` → `ProductType` rename. See `6.0-product-types.md` |
+| `/api/v3/admin/metafield_definitions/*` | `/api/v3/admin/custom_field_definitions/*` | `Metafield` → `CustomField` rename. See `5.4-6.0-custom-fields-rename.md` |
+| `/api/v3/admin/orders/:id/adjustments/*` | `/api/v3/admin/orders/:id/tax_lines`, `discounts`, `fees` (read-only) | Polymorphic `Adjustment` → typed `TaxLine`, `Discount`, `Fee`. See `6.0-split-adjustments.md` |
+| `?expand=master_variant` | `?expand=default_variant` | `is_master` dropped, `default_variant_id` FK. See `6.0-remove-master-variant.md` |
+| `?expand=images` | `?expand=media` | `Image` / `Asset` → `Media`. See `5.4-6.0-product-media-system.md` |
+
+### Field renames on request / response bodies
+
+The following field names change across all endpoints. See `5.4-store-api-naming-standardization.md` for the full list.
+
+| Model | 5.x | 6.0 |
+|---|---|---|
+| `Payment` | `state` | `status` |
+| `Fulfillment` (was Shipment) | `state` | `status` |
+| `Fulfillment` | `shipped_at` | `fulfilled_at` |
+| `FulfillmentItem` (was InventoryUnit) | `state` | `status` |
+| `Return` (was ReturnAuthorization) | `state` | `status` |
+| `GiftCard` | `state` | `status` |
+| `Order` | `shipment_state` | `fulfillment_status` |
+| `Order` | `payment_state` | `payment_status` |
+| `Order` | `shipment_total` | `delivery_total` |
+| `Order` | `promo_total` | `discount_total` |
+| `Order` | `item_count` | `total_quantity` |
+| `Order` | `special_instructions` | `customer_note` |
+| `Order` | `bill_address_id` | `billing_address_id` |
+| `Order` | `ship_address_id` | `shipping_address_id` |
+| `LineItem` | `promo_total` | `discount_total` |
+| `Address` | `firstname` | `first_name` |
+| `Address` | `lastname` | `last_name` |
+| `Address` | `zipcode` | `postal_code` |
+| `OptionType`, `OptionValue`, `CustomFieldDefinition` | `presentation` | `label` |
+| `CreditCard` | `cc_type` | `brand` |
+| `CreditCard` | `last_digits` | `last4` |
+| `CustomFieldDefinition` | `display_on` (string) | `storefront_visible` (boolean) |
+| `CustomFieldDefinition` | `metafield_type` | `field_type` |
+
+### Prefix ID changes
+
+Also tracked in the SDK type definitions. See each linked plan for rationale.
+
+| Model | 5.x prefix | 6.0 prefix |
+|---|---|---|
+| `Fulfillment` (was Shipment) | `shipment_` | `ful_` |
+| `DeliveryMethod` (was ShippingMethod) | — | `dm_` |
+| `DeliveryRate` (was ShippingRate) | — | `dr_` |
+| `FulfillmentItem` (was InventoryUnit) | — | `fi_` |
+| `DeliveryZone` (new) | — | `dz_` |
+| `StockReservation` (new) | — | `res_` |
+| `StockMovement` | — | `sm_` |
+| `Return` (was ReturnAuthorization) | — | `ret_` |
+| `Exchange` (new) | — | `exch_` |
+| `Claim` (new) | — | `claim_` |
+| `Channel` (new) | — | `ch_` |
+| `Catalog` (new) | — | `cat_` |
+| `Company` (new) | — | `comp_` |
+| `CompanyLocation` (new) | — | `cloc_` |
+| `CompanyContact` (new) | — | `cc_` |
+| `ProductListing` (replaces StoreProduct) | — | `pl_` |
+| `Collection` (new) | — | `coll_` |
+| `ProductType` (was Prototype) | `proto_` | `pt_` |
+| `Customer` (was User) | `user_` | `cust_` |
+| `AdminUser` | `admin_` | `adm_` |
+| `CustomField` (was Metafield) | `mf_` | `cf_` |
+| `CustomFieldDefinition` (was MetafieldDefinition) | `mfdef_` | `cfdef_` |
+| `Media` (was Image/Asset) | `image_`/`asset_` | `media_` |
+
+## Endpoint list
+
+Each endpoint below is tracked as `[ ]` (pending) or `[x]` (shipped). When you implement one, flip the checkbox in the same PR. Endpoints are grouped by resource. Removed/renamed 5.x endpoints are NOT listed — see the table above.
+
+### Authentication
+- [x] `POST /api/v3/admin/auth/login` — admin user login (JWT + refresh token)
+- [x] `POST /api/v3/admin/auth/refresh` — rotate refresh token, return new JWT
+- [ ] `DELETE /api/v3/admin/auth/logout` — invalidate JWT and refresh token
+- [x] `GET /api/v3/admin/me` — current admin user + serialized permissions
+
+### Products (⭐ high priority)
+- [x] `GET /api/v3/admin/products` — list (Ransack, sort, paginate)
+- [x] `GET /api/v3/admin/products/:id`
+- [x] `POST /api/v3/admin/products` — with nested variants, prices, `category_ids`
+- [x] `PATCH /api/v3/admin/products/:id`
+- [x] `DELETE /api/v3/admin/products/:id` — soft delete
+- [x] `POST /api/v3/admin/products/:id/clone`
+- [ ] `PATCH /api/v3/admin/products/bulk_update` — bulk status/category/tags
+
+> **6.0 field changes:** `shipping_category_id` is dropped (fulfillment types come from `ProductType.fulfillment_types`). `prototype_id` → `product_type_id`. `taxon_ids` → `category_ids`. Product has `default_variant_id` FK (no more `is_master`).
+
+### Variants (nested under Products)
+- [x] `GET /api/v3/admin/products/:product_id/variants`
+- [x] `GET /api/v3/admin/products/:product_id/variants/:id`
+- [x] `POST /api/v3/admin/products/:product_id/variants` — with nested prices
+- [x] `PATCH /api/v3/admin/products/:product_id/variants/:id`
+- [x] `DELETE /api/v3/admin/products/:product_id/variants/:id`
+
+### Prices
+Managed via nested variant params — no standalone endpoints.
+
+### Product Media (nested under Products, replaces Assets)
+- [x] `GET /api/v3/admin/products/:product_id/media` — list (filterable by `media_type`)
+- [x] `POST /api/v3/admin/products/:product_id/media` — upload via multipart OR `source_url` param (async download). Params: `media_type`, `alt`, `position`, `variant_ids`
+- [x] `PATCH /api/v3/admin/products/:product_id/media/:id` — update alt, position, variant assignment
+- [x] `DELETE /api/v3/admin/products/:product_id/media/:id`
+
+### Digital Assets (nested under Products)
+- [ ] `GET /api/v3/admin/products/:product_id/digital_assets`
+- [ ] `POST /api/v3/admin/products/:product_id/digital_assets`
+- [ ] `PATCH /api/v3/admin/products/:product_id/digital_assets/:id`
+- [ ] `DELETE /api/v3/admin/products/:product_id/digital_assets/:id`
+
+### Option Types
+- [x] `GET /api/v3/admin/option_types`
+- [x] `GET /api/v3/admin/option_types/:id`
+- [x] `POST /api/v3/admin/option_types`
+- [x] `PATCH /api/v3/admin/option_types/:id`
+- [x] `DELETE /api/v3/admin/option_types/:id`
+
+### Option Values (nested under Option Types)
+- [x] `GET /api/v3/admin/option_types/:option_type_id/option_values`
+- [x] `POST /api/v3/admin/option_types/:option_type_id/option_values`
+- [x] `PATCH /api/v3/admin/option_types/:option_type_id/option_values/:id`
+- [x] `DELETE /api/v3/admin/option_types/:option_type_id/option_values/:id`
+
+### Product Types (renamed from Prototypes)
+- [ ] `GET /api/v3/admin/product_types`
+- [ ] `GET /api/v3/admin/product_types/:id`
+- [ ] `POST /api/v3/admin/product_types`
+- [ ] `PATCH /api/v3/admin/product_types/:id`
+- [ ] `DELETE /api/v3/admin/product_types/:id`
+
+> **6.0:** `fulfillment_types` JSON array column (`['shipping']` default). Product types can require specific `CustomFieldDefinition`s via nested definition records. See `6.0-product-types.md`.
+
+### Categories (renamed from Taxons; Taxonomy dropped)
+- [x] `GET /api/v3/admin/categories` — list with tree metadata
+- [x] `GET /api/v3/admin/categories/:id`
+- [ ] `POST /api/v3/admin/categories`
+- [ ] `PATCH /api/v3/admin/categories/:id`
+- [ ] `DELETE /api/v3/admin/categories/:id`
+- [ ] `PATCH /api/v3/admin/categories/:id/reposition` — reposition in tree
+
+> **6.0:** `Spree::Category` belongs directly to `Spree::Store` (no Taxonomy). `Classification` → `ProductCategory`. See `6.0-replace-taxons-with-categories.md`.
+
+### Product Categories (nested under Categories — product assignments)
+- [ ] `GET /api/v3/admin/categories/:category_id/products`
+- [ ] `POST /api/v3/admin/categories/:category_id/products` — assign
+- [ ] `PATCH /api/v3/admin/categories/:category_id/products/:product_id` — update position
+- [ ] `DELETE /api/v3/admin/categories/:category_id/products/:product_id` — unassign
+
+### Collections (new in 6.0)
+- [ ] `GET /api/v3/admin/collections`
+- [ ] `GET /api/v3/admin/collections/:id`
+- [ ] `POST /api/v3/admin/collections` — with nested `rules` (automatic) or manual product list
+- [ ] `PATCH /api/v3/admin/collections/:id`
+- [ ] `DELETE /api/v3/admin/collections/:id`
+
+> **6.0:** Collections replace the "smart taxon" (`automatic: true`, `rules_match_policy`) feature. `CollectionRule` replaces `TaxonRule`. See `6.0-replace-taxons-with-categories.md`.
+
+### Channels (new in 6.0)
+- [ ] `GET /api/v3/admin/channels`
+- [ ] `GET /api/v3/admin/channels/:id`
+- [ ] `POST /api/v3/admin/channels`
+- [ ] `PATCH /api/v3/admin/channels/:id`
+- [ ] `DELETE /api/v3/admin/channels/:id`
+
+> **6.0:** A Channel is a sales surface (POS, Storefront A, Marketplace, etc.). See `6.0-channels-catalogs-b2b.md`.
+
+### Product Listings (nested under Channels, replaces StoreProduct)
+- [ ] `GET /api/v3/admin/channels/:channel_id/product_listings`
+- [ ] `POST /api/v3/admin/channels/:channel_id/product_listings`
+- [ ] `DELETE /api/v3/admin/channels/:channel_id/product_listings/:id`
+- [ ] `POST /api/v3/admin/channels/:channel_id/product_listings/bulk` — bulk add/remove
+
+### Catalogs (new in 6.0, B2B)
+- [ ] `GET /api/v3/admin/catalogs`
+- [ ] `GET /api/v3/admin/catalogs/:id`
+- [ ] `POST /api/v3/admin/catalogs`
+- [ ] `PATCH /api/v3/admin/catalogs/:id`
+- [ ] `DELETE /api/v3/admin/catalogs/:id`
+- [ ] `GET /api/v3/admin/catalogs/:id/products`
+- [ ] `POST /api/v3/admin/catalogs/:id/products` — bulk assign
+- [ ] `DELETE /api/v3/admin/catalogs/:id/products/:product_id`
+- [ ] `POST /api/v3/admin/catalogs/:id/assign` — assign catalog to companies/locations
+
+### Companies (new in 6.0, B2B)
+- [ ] `GET /api/v3/admin/companies`
+- [ ] `GET /api/v3/admin/companies/:id`
+- [ ] `POST /api/v3/admin/companies`
+- [ ] `PATCH /api/v3/admin/companies/:id`
+- [ ] `DELETE /api/v3/admin/companies/:id`
+
+### Company Locations (nested under Companies)
+- [ ] `GET /api/v3/admin/companies/:company_id/locations`
+- [ ] `POST /api/v3/admin/companies/:company_id/locations`
+- [ ] `GET /api/v3/admin/company_locations/:id`
+- [ ] `PATCH /api/v3/admin/company_locations/:id`
+- [ ] `DELETE /api/v3/admin/company_locations/:id`
+
+### Company Contacts (nested under Company Locations)
+- [ ] `GET /api/v3/admin/company_locations/:location_id/contacts`
+- [ ] `POST /api/v3/admin/company_locations/:location_id/contacts`
+- [ ] `PATCH /api/v3/admin/company_contacts/:id`
+- [ ] `DELETE /api/v3/admin/company_contacts/:id`
+
+### Orders (⭐ high priority)
+- [x] `GET /api/v3/admin/orders`
+- [x] `GET /api/v3/admin/orders/:id`
+- [x] `POST /api/v3/admin/orders` — create draft
+- [x] `PATCH /api/v3/admin/orders/:id`
+- [x] `DELETE /api/v3/admin/orders/:id`
+- [x] `PATCH /api/v3/admin/orders/:id/complete`
+- [x] `PATCH /api/v3/admin/orders/:id/cancel`
+- [x] `PATCH /api/v3/admin/orders/:id/approve`
+- [x] `PATCH /api/v3/admin/orders/:id/resume`
+- [x] `POST /api/v3/admin/orders/:id/resend_confirmation`
+
+> **6.0:** Order state machine dropped (derived status from line items + fulfillments + payments — see `6.0-cart-order-split.md`). `PATCH /next` and `/advance` no longer apply (that's cart-side checkout progression). Cart and Order are separate models; `LineItem.owner` is polymorphic. Order gains `channel_id`, `company_location_id`, `withdrawal_eligible_until` FKs.
+
+### Line Items (nested under Orders)
+- [x] `GET /api/v3/admin/orders/:order_id/line_items`
+- [x] `POST /api/v3/admin/orders/:order_id/line_items`
+- [x] `PATCH /api/v3/admin/orders/:order_id/line_items/:id`
+- [x] `DELETE /api/v3/admin/orders/:order_id/line_items/:id`
+
+### Fulfillments (nested under Orders; replaces Shipments)
+- [x] `GET /api/v3/admin/orders/:order_id/fulfillments`
+- [x] `GET /api/v3/admin/orders/:order_id/fulfillments/:id`
+- [ ] `POST /api/v3/admin/orders/:order_id/fulfillments`
+- [x] `PATCH /api/v3/admin/orders/:order_id/fulfillments/:id`
+- [x] `PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/fulfill` — mark as fulfilled
+- [x] `PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/cancel`
+- [x] `PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/resume`
+- [x] `PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/split`
+
+> **6.0:** Third-party fulfillment via `FulfillmentProvider` interface. `pickup_point_data` JSON snapshot for pickup points. See `6.0-fulfillment-and-delivery.md`.
+
+### Payments (nested under Orders)
+- [x] `GET /api/v3/admin/orders/:order_id/payments`
+- [x] `GET /api/v3/admin/orders/:order_id/payments/:id`
+- [x] `POST /api/v3/admin/orders/:order_id/payments`
+- [x] `PATCH /api/v3/admin/orders/:order_id/payments/:id/capture`
+- [x] `PATCH /api/v3/admin/orders/:order_id/payments/:id/void`
+
+### Refunds (nested under Orders)
+- [x] `GET /api/v3/admin/orders/:order_id/refunds`
+- [x] `POST /api/v3/admin/orders/:order_id/refunds` — with `payment_id` in body
+- [ ] `PATCH /api/v3/admin/orders/:order_id/refunds/:id`
+
+### Tax Lines (nested under Orders, read-only; replaces Adjustments)
+- [ ] `GET /api/v3/admin/orders/:order_id/tax_lines`
+
+### Discounts (nested under Orders, read-only; replaces Adjustments)
+- [ ] `GET /api/v3/admin/orders/:order_id/discounts`
+
+### Fees (nested under Orders, read-only; replaces Adjustments)
+- [ ] `GET /api/v3/admin/orders/:order_id/fees`
+
+> **6.0:** Polymorphic `Spree::Adjustment` is dropped. Tax, discount, and fee data is returned via typed, read-only endpoints. See `6.0-split-adjustments.md`.
+
+### Order Customer Assignment
+- [ ] `PUT /api/v3/admin/orders/:order_id/customer` — assign customer
+- [ ] `DELETE /api/v3/admin/orders/:order_id/customer` — remove customer
+
+### Order Discounts (promotion application)
+- [ ] `POST /api/v3/admin/orders/:order_id/discounts` — apply promotion or coupon
+- [ ] `DELETE /api/v3/admin/orders/:order_id/discounts/:id` — remove
+
+### Returns (new in 6.0)
+- [ ] `GET /api/v3/admin/returns`
+- [ ] `GET /api/v3/admin/orders/:order_id/returns`
+- [ ] `GET /api/v3/admin/returns/:id`
+- [ ] `POST /api/v3/admin/orders/:order_id/returns`
+- [ ] `PATCH /api/v3/admin/returns/:id`
+- [ ] `DELETE /api/v3/admin/returns/:id`
+- [ ] `POST /api/v3/admin/returns/:id/approve`
+- [ ] `POST /api/v3/admin/returns/:id/receive`
+- [ ] `POST /api/v3/admin/returns/:id/refund`
+
+### Return Items (nested under Returns)
+- [ ] `PATCH /api/v3/admin/returns/:return_id/items/:id` — reception + acceptance status
+
+### Exchanges (new in 6.0)
+- [ ] `GET /api/v3/admin/exchanges`
+- [ ] `GET /api/v3/admin/orders/:order_id/exchanges`
+- [ ] `GET /api/v3/admin/exchanges/:id`
+- [ ] `POST /api/v3/admin/orders/:order_id/exchanges`
+- [ ] `PATCH /api/v3/admin/exchanges/:id`
+- [ ] `POST /api/v3/admin/exchanges/:id/approve`
+- [ ] `POST /api/v3/admin/exchanges/:id/receive`
+- [ ] `POST /api/v3/admin/exchanges/:id/fulfill`
+
+### Claims (new in 6.0)
+- [ ] `GET /api/v3/admin/claims`
+- [ ] `GET /api/v3/admin/orders/:order_id/claims`
+- [ ] `GET /api/v3/admin/claims/:id`
+- [ ] `POST /api/v3/admin/orders/:order_id/claims`
+- [ ] `PATCH /api/v3/admin/claims/:id`
+- [ ] `POST /api/v3/admin/claims/:id/approve`
+- [ ] `POST /api/v3/admin/claims/:id/resolve`
+
+> **6.0:** Returns, Exchanges, and Claims are first-class models. Replaces the `ReturnAuthorization → CustomerReturn → Reimbursement` chain. See `6.0-returns-exchanges-claims.md`.
+
+### Customers (users)
+- [ ] `GET /api/v3/admin/customers`
+- [ ] `GET /api/v3/admin/customers/:id`
+- [ ] `POST /api/v3/admin/customers`
+- [ ] `PATCH /api/v3/admin/customers/:id`
+- [ ] `DELETE /api/v3/admin/customers/:id`
+- [ ] `POST /api/v3/admin/customers/:id/anonymize` — GDPR right to erasure
+- [ ] `GET /api/v3/admin/customers/:id/export` — GDPR data export (returns JSON download URL)
+
+> **6.0:** `Spree.user_class` → `Spree.customer_class`. `Spree::LegacyUser` → `Spree::Customer`. Anonymize + export endpoints from `5.4-6.0-eu-legal-compliance.md`.
+
+### Customer Addresses (nested under Customers)
+- [ ] `GET /api/v3/admin/customers/:customer_id/addresses`
+- [ ] `POST /api/v3/admin/customers/:customer_id/addresses`
+- [ ] `PATCH /api/v3/admin/customers/:customer_id/addresses/:id`
+- [ ] `DELETE /api/v3/admin/customers/:customer_id/addresses/:id`
+
+### Store Credits (nested under Customers)
+- [ ] `GET /api/v3/admin/customers/:customer_id/store_credits`
+- [ ] `GET /api/v3/admin/customers/:customer_id/store_credits/:id`
+- [ ] `POST /api/v3/admin/customers/:customer_id/store_credits`
+- [ ] `PATCH /api/v3/admin/customers/:customer_id/store_credits/:id`
+- [ ] `DELETE /api/v3/admin/customers/:customer_id/store_credits/:id`
+
+### Gift Cards
+- [ ] `GET /api/v3/admin/gift_cards`
+- [ ] `GET /api/v3/admin/gift_cards/:id`
+- [ ] `POST /api/v3/admin/gift_cards`
+- [ ] `PATCH /api/v3/admin/gift_cards/:id`
+- [ ] `DELETE /api/v3/admin/gift_cards/:id`
+- [ ] `POST /api/v3/admin/gift_card_batches` — batch create
+
+### Customer Groups
+- [ ] `GET /api/v3/admin/customer_groups`
+- [ ] `GET /api/v3/admin/customer_groups/:id`
+- [ ] `POST /api/v3/admin/customer_groups`
+- [ ] `PATCH /api/v3/admin/customer_groups/:id`
+- [ ] `DELETE /api/v3/admin/customer_groups/:id`
+
+### Customer Group Members (nested under Customer Groups)
+- [ ] `GET /api/v3/admin/customer_groups/:customer_group_id/members`
+- [ ] `POST /api/v3/admin/customer_groups/:customer_group_id/members` — bulk add
+- [ ] `DELETE /api/v3/admin/customer_groups/:customer_group_id/members/:id`
+- [ ] `DELETE /api/v3/admin/customer_groups/:customer_group_id/members` — bulk remove
+
+### Newsletter Subscribers
+- [ ] `GET /api/v3/admin/newsletter_subscribers`
+- [ ] `DELETE /api/v3/admin/newsletter_subscribers/:id`
+
+### Tax Exemption Certificates (nested under Companies; B2B)
+- [ ] `GET /api/v3/admin/companies/:company_id/tax_exemption_certificates`
+- [ ] `POST /api/v3/admin/companies/:company_id/tax_exemption_certificates`
+- [ ] `PATCH /api/v3/admin/tax_exemption_certificates/:id`
+- [ ] `DELETE /api/v3/admin/tax_exemption_certificates/:id`
+
+### Promotions
+- [ ] `GET /api/v3/admin/promotions`
+- [ ] `GET /api/v3/admin/promotions/:id`
+- [ ] `POST /api/v3/admin/promotions`
+- [ ] `PATCH /api/v3/admin/promotions/:id`
+- [ ] `DELETE /api/v3/admin/promotions/:id`
+- [ ] `POST /api/v3/admin/promotions/:id/clone`
+
+### Promotion Actions (nested under Promotions)
+- [ ] `GET /api/v3/admin/promotions/:promotion_id/actions`
+- [ ] `POST /api/v3/admin/promotions/:promotion_id/actions`
+- [ ] `PATCH /api/v3/admin/promotions/:promotion_id/actions/:id`
+- [ ] `DELETE /api/v3/admin/promotions/:promotion_id/actions/:id`
+
+### Promotion Rules (nested under Promotions)
+- [ ] `GET /api/v3/admin/promotions/:promotion_id/rules`
+- [ ] `POST /api/v3/admin/promotions/:promotion_id/rules`
+- [ ] `PATCH /api/v3/admin/promotions/:promotion_id/rules/:id`
+- [ ] `DELETE /api/v3/admin/promotions/:promotion_id/rules/:id`
+
+### Coupon Codes (nested under Promotions, read-only)
+- [ ] `GET /api/v3/admin/promotions/:promotion_id/coupon_codes`
+
+### Stock Locations
+- [ ] `GET /api/v3/admin/stock_locations`
+- [ ] `GET /api/v3/admin/stock_locations/:id`
+- [ ] `POST /api/v3/admin/stock_locations`
+- [ ] `PATCH /api/v3/admin/stock_locations/:id`
+- [ ] `DELETE /api/v3/admin/stock_locations/:id`
+
+### Stock Items
+- [ ] `GET /api/v3/admin/stock_items` — filterable by stock_location, variant
+- [ ] `PATCH /api/v3/admin/stock_items/:id`
+- [ ] `DELETE /api/v3/admin/stock_items/:id`
+
+### Stock Movements (read-only; typed in 6.0)
+- [ ] `GET /api/v3/admin/stock_movements` — filterable by `kind`, `fulfillment_id`, `order_id`, `return_id`, `stock_transfer_id`
+
+> **6.0:** `StockMovement` gains `kind` enum (`received`, `allocated`, `shipped`, `released`, `adjusted`) + concrete FKs to the originating event. See `6.0-typed-stock-movements.md`.
+
+### Stock Reservations (read-only; new in 6.0)
+- [ ] `GET /api/v3/admin/stock_reservations` — filterable by variant, order, cart
+- [ ] `DELETE /api/v3/admin/stock_reservations/:id` — manual release
+
+> **6.0:** Time-limited reservations during checkout. See `6.0-stock-reservations.md`.
+
+### Stock Transfers
+- [ ] `GET /api/v3/admin/stock_transfers`
+- [ ] `GET /api/v3/admin/stock_transfers/:id`
+- [ ] `POST /api/v3/admin/stock_transfers`
+- [ ] `DELETE /api/v3/admin/stock_transfers/:id`
+
+### Price Lists
+- [ ] `GET /api/v3/admin/price_lists`
+- [ ] `GET /api/v3/admin/price_lists/:id`
+- [ ] `POST /api/v3/admin/price_lists`
+- [ ] `PATCH /api/v3/admin/price_lists/:id`
+- [ ] `DELETE /api/v3/admin/price_lists/:id`
+
+### Price Rules (nested under Price Lists)
+- [ ] `GET /api/v3/admin/price_lists/:price_list_id/price_rules`
+- [ ] `POST /api/v3/admin/price_lists/:price_list_id/price_rules`
+- [ ] `PATCH /api/v3/admin/price_lists/:price_list_id/price_rules/:id`
+- [ ] `DELETE /api/v3/admin/price_lists/:price_list_id/price_rules/:id`
+
+### Price List Products (nested under Price Lists)
+- [ ] `GET /api/v3/admin/price_lists/:price_list_id/products`
+- [ ] `POST /api/v3/admin/price_lists/:price_list_id/products` — bulk add
+- [ ] `DELETE /api/v3/admin/price_lists/:price_list_id/products` — bulk remove
+
+### Price History (read-only; EU Omnibus compliance)
+- [ ] `GET /api/v3/admin/products/:product_id/price_history` — per-variant history for Omnibus "lowest price in 30 days"
+
+> **6.0:** See `5.4-6.0-eu-legal-compliance.md`.
+
+### Payment Methods
+- [ ] `GET /api/v3/admin/payment_methods`
+- [ ] `GET /api/v3/admin/payment_methods/:id`
+- [ ] `POST /api/v3/admin/payment_methods`
+- [ ] `PATCH /api/v3/admin/payment_methods/:id`
+- [ ] `DELETE /api/v3/admin/payment_methods/:id`
+
+### Delivery Methods (replaces Shipping Methods)
+- [ ] `GET /api/v3/admin/delivery_methods`
+- [ ] `GET /api/v3/admin/delivery_methods/:id`
+- [ ] `POST /api/v3/admin/delivery_methods`
+- [ ] `PATCH /api/v3/admin/delivery_methods/:id`
+- [ ] `DELETE /api/v3/admin/delivery_methods/:id`
+
+> **6.0:** No more `calculator_id`. New fields: `rate_provider` (class name), `fulfillment_provider` (class name), `pickup_point_provider` (for third-party pickup), `fulfillment_type` (enum: `shipping`, `pickup`, `pickup_point`, `digital`, `local_delivery`). See `6.0-delivery-rate-provider.md`, `6.0-fulfillment-and-delivery.md`.
+
+### Delivery Zones (new in 6.0, replaces shipping Zones)
+- [ ] `GET /api/v3/admin/delivery_zones`
+- [ ] `GET /api/v3/admin/delivery_zones/:id`
+- [ ] `POST /api/v3/admin/delivery_zones`
+- [ ] `PATCH /api/v3/admin/delivery_zones/:id`
+- [ ] `DELETE /api/v3/admin/delivery_zones/:id`
+
+### Delivery Zone Members (nested)
+- [ ] `GET /api/v3/admin/delivery_zones/:zone_id/members`
+- [ ] `POST /api/v3/admin/delivery_zones/:zone_id/members`
+- [ ] `DELETE /api/v3/admin/delivery_zones/:zone_id/members/:id`
+
+### Tax Categories
+- [x] `GET /api/v3/admin/tax_categories`
+- [x] `GET /api/v3/admin/tax_categories/:id`
+- [ ] `POST /api/v3/admin/tax_categories`
+- [ ] `PATCH /api/v3/admin/tax_categories/:id`
+- [ ] `DELETE /api/v3/admin/tax_categories/:id`
+
+### Tax Rates
+- [ ] `GET /api/v3/admin/tax_rates`
+- [ ] `GET /api/v3/admin/tax_rates/:id`
+- [ ] `POST /api/v3/admin/tax_rates`
+- [ ] `PATCH /api/v3/admin/tax_rates/:id`
+- [ ] `DELETE /api/v3/admin/tax_rates/:id`
+
+> **6.0:** `zone_id` FK is dropped. `TaxRate` gets direct `country_id` + `state_id` FKs. Tax logic moves behind a `TaxProvider` interface. See `6.0-tax-provider.md`.
+
+### Markets
+- [ ] `GET /api/v3/admin/markets`
+- [ ] `GET /api/v3/admin/markets/:id`
+- [ ] `POST /api/v3/admin/markets`
+- [ ] `PATCH /api/v3/admin/markets/:id`
+- [ ] `DELETE /api/v3/admin/markets/:id`
+
+### Countries
+- [ ] `GET /api/v3/admin/countries`
+- [ ] `GET /api/v3/admin/countries/:id`
+
+### Store Settings
+- [x] `GET /api/v3/admin/store`
+- [x] `PATCH /api/v3/admin/store`
+
+### Policies
+- [ ] `GET /api/v3/admin/policies`
+- [ ] `GET /api/v3/admin/policies/:id`
+- [ ] `POST /api/v3/admin/policies`
+- [ ] `PATCH /api/v3/admin/policies/:id`
+- [ ] `DELETE /api/v3/admin/policies/:id`
+
+### Admin Users
+- [ ] `GET /api/v3/admin/admin_users`
+- [ ] `GET /api/v3/admin/admin_users/:id`
+- [ ] `POST /api/v3/admin/admin_users`
+- [ ] `PATCH /api/v3/admin/admin_users/:id`
+- [ ] `DELETE /api/v3/admin/admin_users/:id`
+
+> **6.0:** `Spree::LegacyAdminUser` → `Spree::AdminUser`. Owns auth stack (no Devise). See `6.0-platform-auth.md`.
+
+### Roles
+- [ ] `GET /api/v3/admin/roles`
+- [ ] `GET /api/v3/admin/roles/:id`
+- [ ] `POST /api/v3/admin/roles`
+- [ ] `PATCH /api/v3/admin/roles/:id`
+- [ ] `DELETE /api/v3/admin/roles/:id`
+
+### Invitations
+- [ ] `GET /api/v3/admin/invitations`
+- [ ] `POST /api/v3/admin/invitations`
+- [ ] `DELETE /api/v3/admin/invitations/:id`
+- [ ] `PATCH /api/v3/admin/invitations/:id/resend`
+
+### Custom Field Definitions (renamed from Metafield Definitions)
+- [ ] `GET /api/v3/admin/custom_field_definitions`
+- [ ] `GET /api/v3/admin/custom_field_definitions/:id`
+- [ ] `POST /api/v3/admin/custom_field_definitions`
+- [ ] `PATCH /api/v3/admin/custom_field_definitions/:id`
+- [ ] `DELETE /api/v3/admin/custom_field_definitions/:id`
+
+> **6.0:** `display_on` → `storefront_visible` (boolean). `metafield_type` → `field_type`. See `5.4-6.0-custom-fields-rename.md`.
+
+### Custom Fields (polymorphic, nested under any resource)
+- [ ] `GET /api/v3/admin/:resource_type/:resource_id/custom_fields`
+- [ ] `POST /api/v3/admin/:resource_type/:resource_id/custom_fields`
+- [ ] `PATCH /api/v3/admin/:resource_type/:resource_id/custom_fields/:id`
+- [ ] `DELETE /api/v3/admin/:resource_type/:resource_id/custom_fields/:id`
+
+### Translations (polymorphic, nested under translatable resources)
+- [ ] `GET /api/v3/admin/:resource_type/:resource_id/translations`
+- [ ] `PATCH /api/v3/admin/:resource_type/:resource_id/translations`
+
+### Tags
+- [ ] `GET /api/v3/admin/tags`
+- [ ] `POST /api/v3/admin/tags`
+- [ ] `DELETE /api/v3/admin/tags/:id`
+
+### Refund Reasons
+- [ ] `GET /api/v3/admin/refund_reasons`
+- [ ] `GET /api/v3/admin/refund_reasons/:id`
+- [ ] `POST /api/v3/admin/refund_reasons`
+- [ ] `PATCH /api/v3/admin/refund_reasons/:id`
+- [ ] `DELETE /api/v3/admin/refund_reasons/:id`
+
+### Return Reasons (renamed from Return Authorization Reasons)
+- [ ] `GET /api/v3/admin/return_reasons`
+- [ ] `GET /api/v3/admin/return_reasons/:id`
+- [ ] `POST /api/v3/admin/return_reasons`
+- [ ] `PATCH /api/v3/admin/return_reasons/:id`
+- [ ] `DELETE /api/v3/admin/return_reasons/:id`
+
+### Store Credit Categories
+- [ ] `GET /api/v3/admin/store_credit_categories`
+- [ ] `GET /api/v3/admin/store_credit_categories/:id`
+- [ ] `POST /api/v3/admin/store_credit_categories`
+- [ ] `PATCH /api/v3/admin/store_credit_categories/:id`
+- [ ] `DELETE /api/v3/admin/store_credit_categories/:id`
+
+### Webhook Endpoints
+- [ ] `GET /api/v3/admin/webhook_endpoints`
+- [ ] `GET /api/v3/admin/webhook_endpoints/:id`
+- [ ] `POST /api/v3/admin/webhook_endpoints`
+- [ ] `PATCH /api/v3/admin/webhook_endpoints/:id`
+- [ ] `DELETE /api/v3/admin/webhook_endpoints/:id`
+
+### Webhook Deliveries (nested under Webhook Endpoints, read-only)
+- [ ] `GET /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries`
+- [ ] `GET /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id`
+
+### API Keys
+- [ ] `GET /api/v3/admin/api_keys`
+- [ ] `POST /api/v3/admin/api_keys`
+- [ ] `PATCH /api/v3/admin/api_keys/:id`
+- [ ] `DELETE /api/v3/admin/api_keys/:id`
+- [ ] `PATCH /api/v3/admin/api_keys/:id/revoke`
+
+### Integrations
+- [ ] `GET /api/v3/admin/integrations`
+- [ ] `GET /api/v3/admin/integrations/:id`
+- [ ] `POST /api/v3/admin/integrations`
+- [ ] `PATCH /api/v3/admin/integrations/:id`
+- [ ] `DELETE /api/v3/admin/integrations/:id`
+
+> **6.0:** Integration records back the TaxProvider, DeliveryRateProvider, FulfillmentProvider, and PickupPointProvider interfaces (along with external search, email, etc.).
+
+### Reports
+- [ ] `GET /api/v3/admin/reports`
+- [ ] `GET /api/v3/admin/reports/:id`
+- [ ] `POST /api/v3/admin/reports` — generate
+
+### Exports
+- [ ] `GET /api/v3/admin/exports`
+- [ ] `GET /api/v3/admin/exports/:id` — includes download URL
+- [ ] `POST /api/v3/admin/exports`
+
+### Imports
+- [ ] `GET /api/v3/admin/imports`
+- [ ] `GET /api/v3/admin/imports/:id` — status, row counts
+- [ ] `POST /api/v3/admin/imports` — multipart/form-data
+- [ ] `PATCH /api/v3/admin/imports/:id/complete_mapping`
+
+### Dashboard
+- [ ] `GET /api/v3/admin/dashboard/analytics`
+
+## Open Questions
+
+- **Bulk operations envelope** — do we want a single `POST /bulk` endpoint per resource, or per-action bulk routes (`bulk_update`, `bulk_destroy`)? Currently leaning toward per-action for clarity, but it bloats the route table.
+- **Order user assignment** — is `PUT /orders/:id/user` the right shape, or should this be `PATCH /orders/:id { customer_id: ... }`?
+- **Polymorphic custom fields routing** — `/:resource_type/:resource_id/custom_fields` is ugly. Consider a flat `/custom_fields?resource_type=...&resource_id=...` instead.
+- **Translations endpoint** — one PATCH for all locales vs. one PATCH per locale?
+
+## References
+
+- `docs/api-reference/store-api/errors.mdx` — error response conventions (shared)
+- `docs/plans/6.0-admin-spa.md` — consumer of this API
+- `docs/plans/6.0-platform-auth.md` — auth stack and `Spree.admin_user_class` rename
+- `docs/plans/5.4-6.0-custom-fields-rename.md` — Metafields → Custom Fields
+- `docs/plans/6.0-fulfillment-and-delivery.md` — shipping category dropped
diff --git a/docs/plans/6.0-admin-spa.md b/docs/plans/6.0-admin-spa.md
index 5b5a6d7fb4..a78358986c 100644
--- a/docs/plans/6.0-admin-spa.md
+++ b/docs/plans/6.0-admin-spa.md
@@ -1,41 +1,385 @@
# Admin SPA
-**Status:** Design finalized, implementation not started
-**Target:** Spree 6.0
-**Depends on:** API v3 conventions
+**Status:** In Progress
+**Target:** Spree 6.0
+**Depends on:** `6.0-admin-api.md`, `6.0-platform-auth.md`
+**Author:** damian
+**Last updated:** 2026-04-11
+
+## Summary
+
+A new single-page React admin dashboard that replaces the Rails `spree/admin` engine entirely. Client-side only (Vite SPA), built on the new Admin API via `@spree/admin-sdk`, deployed either as static assets bundled into the Spree gem or as a standalone hosted app. Mirrors all admin functionality from the Rails admin while giving plugin authors a modern extension model (table registry, navigation registry, component injection).
## Key Decisions (do not deviate without discussion)
-- Drop thee rails admin panel entirely
-- Create new Vite/TanStack React admin UI
-- Use Admin API and Admin SDK
-- Use Shadcn UI components
-- No server-side rendering
+
+- **Drop the Rails admin panel entirely.** No dual-maintenance. When the SPA reaches feature parity, `spree/admin` is removed.
+- **Vite + TanStack Router + TanStack Query + React Hook Form + shadcn/ui + Tailwind + Biome + Vitest.** Use the newest versions (as of March 2026).
+- **No SSR.** Pure client-side, outputs static files.
+- **Admin API is the only data source.** Never reach into Rails models, never import Rails-rendered HTML.
+- **Route path includes `/$storeId/`** for all authenticated routes (multi-store support). `/` redirects to the current/default store.
+- **Auth via JWT + refresh token.** Access token in React context, refresh token in `localStorage` (or httpOnly cookie when we have a hosted deployment). 401 → auto-refresh via SDK `onUnauthorized` hook → retry.
+- **Permissions are server-driven.** `GET /api/v3/admin/me` returns the CanCanCan rules serialized; SPA mirrors them via `<Can I="..." a="..." />` and the `usePermissions()` hook. Server still enforces `authorize!` — SPA is UX only.
+- **Shadcn/ui copy-paste ownership model** — plugin authors can extend or override components without fighting a component library's abstraction.
+- **Table registry + navigation registry + component injection** are the three extension points. Nothing else is pluggable yet.
+- **No global state library.** TanStack Query handles server state, React Hook Form handles form state, `AuthProvider` + `PermissionProvider` handle session. Add Zustand only if we hit a legitimate client-state problem.
+- **shipping_category_id is not part of product forms** — dropped in 6.0 per `6.0-fulfillment-and-delivery.md`.
+
+## Design Details
+
+### Monorepo location
+
+- Package: `packages/admin/`
+- Depends on: `@spree/admin-sdk` (workspace), `@spree/sdk-core` (workspace)
+- Output: `dist/` (static SPA). Optionally bundled into `spree_admin` gem at build time for zero-config local dev.
+- Dev server: `pnpm dev` → `vite` → `http://localhost:5173`, proxying `/api/*` to `http://localhost:3000`
+
+### Tech stack
+
+| Layer | Choice | Why |
+|---|---|---|
+| Build & dev | **Vite** | Fast HMR, minimal config, outputs static files |
+| Routing | **TanStack Router** | Type-safe routes, file-based convention, loader + beforeLoad hooks integrate with TanStack Query |
+| Data fetching | **TanStack Query** | Caching, background refetches, optimistic updates. `@spree/admin-sdk` calls wrapped in custom hooks (`useProducts`, `useOrder`, ...) |
+| Forms | **React Hook Form + Zod** | Schemas mirror API contracts; Zod schemas can be derived from Typelizer-generated types |
+| UI | **shadcn/ui + Tailwind** | Copy-paste ownership so extensions can override without fighting component APIs |
+| Icons | **lucide-react** | |
+| Auth | **Custom `AuthProvider`** | Token in memory + localStorage; refresh token in localStorage; 58-minute refresh timer; 401 auto-retry via SDK `onUnauthorized` |
+| Permissions | **Custom `PermissionProvider`** | Loads `/api/v3/admin/me` on login, exposes `usePermissions()` + `<Can>` mirroring CanCanCan |
+| State (session) | `AuthProvider` + `PermissionProvider` | Small context, no global store |
+| Linting/formatting | **Biome** | Single tool, fast |
+| Testing | **Vitest + React Testing Library** (unit/integration), **Playwright** (E2E) | |
+| Fonts | **Geist + Geist Mono** | Same as old spree/admin |
+
+### Auth flow
+
+```
+Login → POST /auth/login → { token, refresh_token, user }
+ ↓
+Store in adminClient, AuthProvider state, localStorage
+ ↓
+PermissionProvider fetches /me → { user, permissions: [...] }
+ ↓
+Router beforeLoad guards check `context.auth.isAuthenticated`
+ ↓
+Every 58 min: refresh token → new access + rotated refresh
+ ↓
+On 401 from any API call: SDK onUnauthorized → refresh → retry original request
+```
+
+Concurrent refresh calls are serialized via a shared promise to prevent double-rotation.
+
+### Route structure
+
+```
+src/routes/
+ __root.tsx # router context types
+ login.tsx # public login page
+ _authenticated.tsx # auth guard, sidebar layout
+ index.tsx # redirects to /$defaultStoreId
+ $storeId.tsx # StoreProvider + setStore on adminClient
+ index.tsx # dashboard
+ orders/
+ index.tsx
+ $orderId.tsx
+ drafts.tsx
+ products/
+ index.tsx
+ $productId.tsx
+ customers/
+ ...
+```
+
+- All data-owning routes are `/$storeId/*`. No duplication of routes across storefront-prefix and non-prefixed variants (we had that briefly and removed it).
+- Table list pages live at `/$storeId/{resource}/`, detail pages at `/$storeId/{resource}/$id`.
+- Navigation is built dynamically from the current `storeId` and filtered by permissions.
+
+### Auth + Permission providers
+
+```tsx
+<AuthProvider> {/* login/logout, tokens, refresh */}
+ <PermissionProvider> {/* /me, CanCanCan rule matcher */}
+ <TooltipProvider>
+ <RouterProvider router={router} context={{ auth, permissions }} />
+ </TooltipProvider>
+ </PermissionProvider>
+</AuthProvider>
+```
+
+Router context carries `auth` and `permissions` so `beforeLoad` guards can do:
+
+```tsx
+beforeLoad: ({ context }) => {
+ if (context.permissions.cannot('manage', 'Spree::User')) {
+ throw redirect({ to: '/$storeId' })
+ }
+}
+```
+
+### Table registry
+
+The admin uses a declarative **table registry** to define resource list pages. Mirrors the Rails admin's `Spree.admin.tables` DSL.
+
+A list page needs two things:
+
+1. A **table definition** (`src/tables/orders.tsx`)
+2. A **route** (`src/routes/_authenticated/$storeId/orders/index.tsx`) that renders `<ResourceTable>`
+
+#### Example
+
+```tsx
+// src/tables/orders.tsx
+import { defineTable } from '@/lib/table-registry'
+import { StatusBadge } from '@/components/ui/badge'
+import { formatRelativeTime } from '@/lib/formatters'
+
+defineTable('orders', {
+ title: 'Orders',
+ searchParam: 'multi_search',
+ searchPlaceholder: 'Search orders...',
+ defaultSort: { field: 'completed_at', direction: 'desc' },
+ emptyMessage: 'No orders found',
+ columns: [
+ { key: 'number', label: 'Number', sortable: true, filterable: true, default: true,
+ render: (o) => <Link to="/$storeId/orders/$orderId" params={{ orderId: o.id }}>#{o.number}</Link> },
+ { key: 'fulfillment_status', label: 'Fulfillment', sortable: true, filterable: true, default: true,
+ filterType: 'status',
+ filterOptions: [
+ { value: 'unfulfilled', label: 'Unfulfilled' },
+ { value: 'fulfilled', label: 'Fulfilled' },
+ { value: 'canceled', label: 'Canceled' },
+ ],
+ render: (o) => o.fulfillment_status ? <StatusBadge status={o.fulfillment_status} /> : '—' },
+ { key: 'payment_status', label: 'Payment', sortable: true, filterable: true, default: true,
+ filterType: 'status',
+ filterOptions: [
+ { value: 'paid', label: 'Paid' },
+ { value: 'balance_due', label: 'Balance due' },
+ { value: 'refunded', label: 'Refunded' },
+ ],
+ render: (o) => o.payment_status ? <StatusBadge status={o.payment_status} /> : '—' },
+ { key: 'display_total', label: 'Total', sortable: true, default: true,
+ className: 'text-right tabular-nums',
+ render: (o) => o.display_total },
+ { key: 'completed_at', label: 'Date', sortable: true, default: true, filterType: 'date',
+ render: (o) => o.completed_at ? formatRelativeTime(o.completed_at) : '—' },
+ ],
+})
+```
+
+```tsx
+// src/routes/_authenticated/$storeId/orders/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { ResourceTable, resourceSearchSchema } from '@/components/resource-table'
+import { adminClient } from '@/client'
+import '@/tables/orders'
+
+export const Route = createFileRoute('/_authenticated/$storeId/orders/')({
+ validateSearch: resourceSearchSchema,
+ component: OrdersPage,
+})
+
+function OrdersPage() {
+ const searchParams = Route.useSearch()
+ return (
+ <ResourceTable
+ tableKey="orders"
+ queryKey="orders"
+ queryFn={(params) => adminClient.orders.list(params)}
+ searchParams={searchParams}
+ defaultParams={{ complete: 1 }}
+ />
+ )
+}
+```
+
+`<ResourceTable>` handles toolbar (search, filters, sort, column selector), data fetching, pagination, loading states, and empty states. URL state is persisted via TanStack Router search params (`page`, `sort`, `dir`, `search`, `filters`, `columns`).
+
+#### `defineTable(key, options)` reference
+
+| Option | Type | Description |
+|---|---|---|
+| `title` | `string` | Toolbar title |
+| `columns` | `ColumnDef[]` | Column definitions |
+| `searchParam` | `string` | Ransack search param name (default `name_cont`) |
+| `searchPlaceholder` | `string` | |
+| `defaultSort` | `{ field, direction }` | Default `{ updated_at, desc }` |
+| `emptyIcon`, `emptyMessage` | `ReactNode`, `string` | |
+
+#### `ColumnDef` reference
+
+| Property | Default | Description |
+|---|---|---|
+| `key` | required | Unique identifier, used as Ransack attribute unless `ransackAttribute` is set |
+| `label` | required | Header + toolbar display |
+| `sortable` | `false` | |
+| `filterable` | `false` | Shows in filter drawer |
+| `default` | `false` | Visible by default |
+| `filterType` | `'string'` | `'string' \| 'status' \| 'boolean' \| 'number' \| 'date'` |
+| `filterOptions` | — | For `status` filter |
+| `ransackAttribute` | — | Override when Ransack attribute ≠ column key |
+| `render` | — | Custom cell renderer |
+| `className` | — | CSS class on `<td>` |
+| `displayable` | `true` | `false` for filter-only columns |
+
+#### Filter operators per type
+
+| Type | Operators |
+|---|---|
+| `string` | contains, equals, does not equal, starts with, ends with, is set, is not set |
+| `status` | is, is not, is any of, is none of |
+| `boolean` | is |
+| `number` | eq, gt, gte, lt, lte |
+| `date` | is, after, before, on or after, on or before |
+
+### Extension points
+
+Three extension points only (do not add more without discussion):
+
+1. **Navigation registry** — plugins add sidebar items by registering nav entries with required permissions.
+2. **Table registry** — plugins add/remove/update columns, filters, and sorts on existing tables:
+
+```tsx
+tables.products.addColumn({
+ key: 'vendor',
+ label: 'Vendor',
+ sortable: true,
+ filterable: true,
+ default: true,
+ render: (p) => p.vendor_name ?? '—',
+})
+
+tables.products.removeColumn('inventory')
+
+tables.products.updateColumn('sku', {
+ default: true,
+ label: 'Product SKU',
+})
+```
+
+3. **Component injection** — plugins inject components into defined slots on existing pages (e.g., extra fields on the product form, extra cards on the order detail page). Slot API is still being designed.
+
+### Comparison with Rails admin DSL
+
+| Rails admin | React admin |
+|---|---|
+| `Spree.admin.tables.register(:products, ...)` | `defineTable('products', { ... })` |
+| `Spree.admin.tables.products.add :name, ...` | Column in `columns` array |
+| `type: :custom, partial: '...'` | `render: (row) => <Component />` |
+| `Spree.admin.tables.products.add :col, ...` (in initializer) | `tables.products.addColumn({ ... })` |
+| `Spree.admin.tables.products.remove :col` | `tables.products.removeColumn('col')` |
+| `render_table @collection, :products` | `<ResourceTable tableKey="products" ... />` |
+| `ransack_attribute: 'master_sku'` | `ransackAttribute: 'master_sku'` |
+| `filter_type: :status, value_options: [...]` | `filterType: 'status', filterOptions: [...]` |
+| `displayable: false` | `displayable: false` |
+
+### File structure
+
+```
+packages/admin/
+├── index.html
+├── package.json
+├── vite.config.ts
+├── src/
+│ ├── main.tsx # root provider tree
+│ ├── router.tsx # TanStack Router config
+│ ├── client.ts # admin SDK instance
+│ ├── routeTree.gen.ts # generated
+│ ├── index.css # Tailwind + shadcn theme + Geist fonts
+│ ├── routes/
+│ │ ├── __root.tsx
+│ │ ├── login.tsx
+│ │ └── _authenticated/
+│ │ ├── index.tsx # redirects to /$defaultStoreId
+│ │ ├── $storeId.tsx # StoreProvider
+│ │ └── $storeId/
+│ │ ├── index.tsx # dashboard
+│ │ ├── orders/
+│ │ ├── products/
+│ │ └── ...
+│ ├── providers/
+│ │ ├── auth-provider.tsx # JWT + refresh token
+│ │ ├── permission-provider.tsx # CanCanCan mirror
+│ │ └── store-provider.tsx # current store context
+│ ├── hooks/
+│ │ ├── use-auth.ts
+│ │ ├── use-products.ts # wraps adminClient.products
+│ │ ├── use-orders.ts
+│ │ └── ...
+│ ├── components/
+│ │ ├── app-sidebar.tsx
+│ │ ├── nav-main.tsx
+│ │ ├── can.tsx # <Can I="..." a="..." />
+│ │ ├── back-button.tsx # history.back() with fallback
+│ │ ├── resource-table.tsx
+│ │ ├── table-toolbar.tsx
+│ │ └── ui/ # shadcn components
+│ ├── tables/
+│ │ ├── orders.tsx # defineTable('orders', ...)
+│ │ ├── products.tsx
+│ │ └── ...
+│ ├── schemas/
+│ │ ├── product.ts # Zod form schemas
+│ │ └── ...
+│ └── lib/
+│ ├── query-client.ts
+│ ├── table-registry.ts # defineTable, getTable, tables proxy
+│ ├── permissions.ts # Subject + Action constants
+│ ├── formatters.ts # formatPrice, formatRelativeTime
+│ └── utils.ts
+```
## Migration Path
-- Remove `spree/admin` engine
-- Create new `packages/admin`
-## Architecture
+### Phase 1 — parity with Rails admin (in progress)
+
+- ✅ Package skeleton, Vite, TanStack Router, TanStack Query
+- ✅ Auth (login, logout, JWT refresh, 401 auto-retry)
+- ✅ Permission provider + `<Can>` + sidebar filtering
+- ✅ Table registry + resource table
+- ✅ Multi-store routing (`$storeId` prefix)
+- ⏳ Products list + detail/edit
+- ⏳ Orders list + detail/edit
+- ⏳ Customers
+- ⏳ Promotions
+- ⏳ Stock, categories, store settings, admin users, roles
+- ⏳ Reports, exports, imports, dashboard
+
+### Phase 2 — extension API
+
+- Navigation registry
+- Component injection slot API
+- Plugin loader / discovery mechanism
+
+### Phase 3 — drop Rails admin
+
+- Remove `spree/admin` engine entirely
+- Update `create-spree-app` scaffolding to install `@spree/admin` by default
+- Update docs
-We should use conventions when handling forms, lists, and other UI components to reduce boilerplate and make it easier for developers to extend the admin dashboard.
+## Constraints on Current Work
-* Build & Dev: Vite (obvious choice for a pure client-side SPA — fast HMR, clean config, outputs static files you can bundle into the Rails gem or deploy standalone)
-* Routing: TanStack Router — type-safe routes, file-based convention, built-in loader pattern pairs perfectly with TanStack Query for prefetching on navigation
-* Data Fetching: TanStack Query — handles caching, background refetches, optimistic updates. Your @spree/admin-sdk becomes the query function layer. Wrap SDK methods as custom hooks (useProducts, useOrder, etc.)
-* Forms: React Hook Form + Zod for validation schemas. Zod schemas can mirror your API contracts, and if you're auto-generating types from OpenAPI specs, you can derive Zod schemas from the same source
-* UI: shadcn/ui + Tailwind. Copy-paste ownership model means your plugin authors can extend or override components without fighting a component library's abstraction
-* Auth: For JWT — store the access token in memory (React context/state), refresh token in an httpOnly cookie if possible, or memory as fallback. TanStack Router's beforeLoad guards check auth state before rendering protected routes. A simple AuthProvider context that exposes login(), logout(), getToken() and injects the token into the SDK client instance
-* State: You likely don't need a global state library. TanStack Query covers server state, React Hook Form covers form state, and a small AuthContext covers the session. If something edges toward complex client-only state later, Zustand is the lightest option that won't fight you
-* Linting/Formatting: Biome — single tool, fast, no ESLint/Prettier config sprawl
-* Testing: Vitest + React Testing Library for unit/integration, Playwright for E2E
+- **No new routes outside `/_authenticated/$storeId/`.** Always prefix with store.
+- **Always use SDK types.** Never hand-write API response shapes. If a type is wrong, fix the Rails serializer + run Typelizer, don't cast in the SPA.
+- **No `useMemo`/`useCallback` without reason.** Keep components small and readable; optimize only when profiling says so.
+- **No imperative navigation hacks.** Use TanStack Router `Link` and `navigate`.
+- **All forms use React Hook Form + Zod.** Never use uncontrolled forms or manual `useState` for form state.
+- **All data fetching goes through TanStack Query hooks in `src/hooks/`.** Never call `adminClient` directly from components.
+- **Permission-gate UI optimistically.** Show the button, handle 403 with a toast. Only hide when there's a clear `read` denial.
+- **All nav items, routes, and action buttons that correspond to Admin API resources must pass a `subject` to `<Can>` or the equivalent check.** Sidebar filtering already does this — keep it consistent.
+- **Field names must match the API.** No `zipcode`, `firstname`, `shipment_state`, `line_items` in SPA code — use `postal_code`, `first_name`, `fulfillment_status`, `items`. See `5.4-store-api-naming-standardization.md`.
-## Extension points
+## Open Questions
-Developers will be able to extend the admin dashboard by adding custom pages, components, and logic.
+- **Plugin distribution** — npm packages? Dynamic imports? Build-time registration? Current default is build-time (`import '@plugin/foo'` in a project's entry file), but we want to support runtime plugin loading for hosted deployments.
+- **Component injection slot API** — named slots like `<Slot name="product.sidebar" />`? Portal-based? React-aria–style provider/consumer?
+- **Theme customization** — how deep? Tailwind config overrides? CSS variables? shadcn theme tokens?
+- **Bundled vs. standalone deployment** — do we ship SPA compiled into the gem, or require a separate static host? Hybrid (gem ships fallback, ops can override URL)?
+- **Offline / optimistic mutations** — TanStack Query supports it but we haven't wired it in. Priority for Phase 2?
-There are 3 main areas where developers can extend the admin dashboard:
+## References
-1. Navigation - needs to be configurable via registry
-2. Tables - record listing, eg. products, orders. Developers need to be able to customize table columns and filters.
-3. Pages - developers should be able to add custom pages, extend routes, and add custom logic.
-3. Components - developers should be able to add custom components and extend existing ones. Developers should be able to inject their own components into existing pages, eg. new fields on product form page.
+- `docs/plans/6.0-admin-api.md` — backing API
+- `docs/plans/6.0-platform-auth.md` — auth model
+- `docs/plans/5.4-store-api-naming-standardization.md` — field naming rules
+- `docs/plans/5.4-6.0-custom-fields-rename.md` — Metafields → Custom Fields
+- `docs/plans/6.0-fulfillment-and-delivery.md` — ShippingCategory dropped
diff --git a/packages/admin/docs/ARCHITECTURE.md b/packages/admin/docs/ARCHITECTURE.md
deleted file mode 100644
index 5930b4a73a..0000000000
--- a/packages/admin/docs/ARCHITECTURE.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# @spree/admin package
-
-## Overview
-
-This is the new admin dashboard for Spree using Spree Admin API (via Spree SDK package in `../sdk`) which will replace existing Rails (full-stack/monolith) admin dashboard located in `../../spree/admin`.
-
-This package will be installed as a dependency when developer creates a new Spree project using `create-spree-app`.
-
-Admin SDK documentation: `packages/sdk/ADMIN_SDK.md`
-
-## Authentication
-
-Authentication is handled by the Spree SDK package via the `secretKey` configuration option. You need a secreat key to use this package. Should read `SPREE_SECRET_KEY` environment variable by default. We also need to support `SPREE_API_URL` environment variable pointing to the Spree backend API (defaults to `http://localhost:3000`)
-
-User authentication is handled via JWT short lived tokens. Everything is built into the Spree SDK package.
-
-```typescript
-import { createSpreeClient } from '@spree/sdk';
-
-// Initialize the client
-const client = createSpreeClient({
- baseUrl: process.env.SPREE_API_URL,
- secretKey: process.env.SPREE_SECRET_KEY,
-});
-
-// Authentication
-const { token, user } = await client.admin.auth.login({
- email: '[email protected]',
- password: 'password123',
-});
-```
-
-## Conventions
-
-We should use conventions when handling forms, lists, and other UI components to reduce boilerplate and make it easier for developers to extend the admin dashboard.
-
-## Tech stack
-
-Let's remember to use the newest versions of each library (as of March 2026).
-
-* Build & Dev: Vite (obvious choice for a pure client-side SPA — fast HMR, clean config, outputs static files you can bundle into the Rails gem or deploy standalone)
-* Routing: TanStack Router — type-safe routes, file-based convention, built-in loader pattern pairs perfectly with TanStack Query for prefetching on navigation
-* Data Fetching: TanStack Query — handles caching, background refetches, optimistic updates. Your @spree/admin-sdk becomes the query function layer. Wrap SDK methods as custom hooks (useProducts, useOrder, etc.)
-* Forms: React Hook Form + Zod for validation schemas. Zod schemas can mirror your API contracts, and if you're auto-generating types from OpenAPI specs, you can derive Zod schemas from the same source
-* UI: shadcn/ui + Tailwind. Copy-paste ownership model means your plugin authors can extend or override components without fighting a component library's abstraction
-* Auth: For JWT — store the access token in memory (React context/state), refresh token in an httpOnly cookie if possible, or memory as fallback. TanStack Router's beforeLoad guards check auth state before rendering protected routes. A simple AuthProvider context that exposes login(), logout(), getToken() and injects the token into the SDK client instance
-* State: You likely don't need a global state library. TanStack Query covers server state, React Hook Form covers form state, and a small AuthContext covers the session. If something edges toward complex client-only state later, Zustand is the lightest option that won't fight you
-* Linting/Formatting: Biome — single tool, fast, no ESLint/Prettier config sprawl
-* Testing: Vitest + React Testing Library for unit/integration, Playwright for E2E
-
-## Extension points
-
-Developers will be able to extend the admin dashboard by adding custom pages, components, and logic.
-
-There are 3 main areas where developers can extend the admin dashboard:
-
-1. Navigation - needs to be configurable via registry
-2. Tables - record listing, eg. products, orders. Developers need to be able to customize table columns and filters.
-3. Pages - developers should be able to add custom pages, extend routes, and add custom logic.
-3. Components - developers should be able to add custom components and extend existing ones. Developers should be able to inject their own components into existing pages, eg. new fields on product form page.
-
-## Design
-
-We can inspire from the rails admin dashboard design, located at `../../spree/admin` (look for `spree_admin.html.erb` layout file and stylesheets located at `../../spree/admin/assets/tailwind`).
diff --git a/packages/admin/docs/tables.mdx b/packages/admin/docs/tables.mdx
deleted file mode 100644
index 1d62af9f2c..0000000000
--- a/packages/admin/docs/tables.mdx
+++ /dev/null
@@ -1,302 +0,0 @@
-# Admin Tables
-
-The admin uses a **table registry** to declaratively define resource list pages. This system provides:
-
-- Declarative column, filter, and sort definitions
-- A generic `<ResourceTable>` component that renders any registered table
-- A mutation API for extensions to add, remove, or update columns on existing tables
-
-This is the React equivalent of the Rails admin's `Spree.admin.tables` DSL.
-
-## Quick start
-
-A resource list page requires two things:
-
-1. A **table definition** that declares columns
-2. A **route** that renders `<ResourceTable>`
-
-### 1. Define the table
-
-Create a file in `src/tables/` (e.g., `src/tables/orders.tsx`):
-
-```tsx
-import { defineTable } from '@/lib/table-registry'
-import { StatusBadge } from '@/components/ui/badge'
-import { formatRelativeTime } from '@/lib/formatters'
-
-defineTable('orders', {
- title: 'Orders',
- searchParam: 'number_cont',
- searchPlaceholder: 'Search orders...',
- defaultSort: { field: 'completed_at', direction: 'desc' },
- emptyMessage: 'No orders found',
- columns: [
- {
- key: 'number',
- label: 'Order',
- sortable: true,
- filterable: true,
- default: true,
- render: (order) => (
- <span className="font-medium text-zinc-950">#{order.number}</span>
- ),
- },
- {
- key: 'status',
- label: 'Status',
- sortable: true,
- filterable: true,
- default: true,
- filterType: 'status',
- filterOptions: [
- { value: 'complete', label: 'Complete' },
- { value: 'canceled', label: 'Canceled' },
- ],
- render: (order) => <StatusBadge status={order.status} />,
- },
- {
- key: 'total',
- label: 'Total',
- sortable: true,
- default: true,
- className: 'text-right tabular-nums',
- render: (order) => order.display_total,
- },
- {
- key: 'completed_at',
- label: 'Date',
- sortable: true,
- filterable: true,
- default: true,
- filterType: 'date',
- className: 'text-sm text-muted-foreground whitespace-nowrap',
- render: (order) => order.completed_at ? formatRelativeTime(order.completed_at) : '—',
- },
- ],
-})
-```
-
-### 2. Create the route
-
-```tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { ResourceTable, resourceSearchSchema } from '@/components/resource-table'
-import { spreeClient } from '@/client'
-import { useAuth } from '@/hooks/use-auth'
-import '@/tables/orders' // registers the table definition
-
-export const Route = createFileRoute('/_authenticated/orders/')({
- validateSearch: resourceSearchSchema,
- component: OrdersPage,
-})
-
-function OrdersPage() {
- const searchParams = Route.useSearch()
- const { token } = useAuth()
-
- return (
- <ResourceTable
- tableKey="orders"
- queryKey="orders"
- queryFn={(params) =>
- spreeClient.admin.orders.list(params, { token: token! })
- }
- searchParams={searchParams}
- />
- )
-}
-```
-
-That's it. The `<ResourceTable>` component handles the toolbar (search, filters, sort, column selector), data fetching, pagination, loading states, and empty states automatically.
-
-## Table definition reference
-
-### `defineTable(key, options)`
-
-Registers a table in the global registry.
-
-| Option | Type | Description |
-|---|---|---|
-| `title` | `string` | Title displayed in the toolbar header (e.g., `'Products'`) |
-| `columns` | `ColumnDef[]` | Column definitions (see below) |
-| `searchParam` | `string` | Ransack search parameter name. Defaults to `'name_cont'` |
-| `searchPlaceholder` | `string` | Placeholder text for the search input |
-| `defaultSort` | `{ field, direction }` | Default sort. Defaults to `{ field: 'updated_at', direction: 'desc' }` |
-| `emptyIcon` | `ReactNode` | Icon shown when the table is empty |
-| `emptyMessage` | `string` | Message shown when the table is empty |
-
-### Column definition (`ColumnDef`)
-
-| Property | Type | Default | Description |
-|---|---|---|---|
-| `key` | `string` | *required* | Unique column identifier, also used as the Ransack attribute for filtering/sorting |
-| `label` | `string` | *required* | Display label in the header and toolbar |
-| `sortable` | `boolean` | `false` | Whether this column can be sorted |
-| `filterable` | `boolean` | `false` | Whether this column appears in the filter drawer |
-| `default` | `boolean` | `false` | Whether this column is visible by default |
-| `filterType` | `'string' \| 'status' \| 'boolean' \| 'number' \| 'date'` | `'string'` | Determines which filter operators are available |
-| `filterOptions` | `{ value, label }[]` | — | Predefined options for `status` filter type |
-| `ransackAttribute` | `string` | — | Override the Ransack attribute name (e.g., `'master_sku'` for a column with `key: 'sku'`) |
-| `render` | `(row: T) => ReactNode` | — | Custom cell renderer. If omitted, renders `row[key]` as plain text |
-| `className` | `string` | — | CSS class applied to the `<td>` element |
-| `displayable` | `boolean` | `true` | Set to `false` for filter-only columns that don't render in the table |
-
-### Filter types and operators
-
-Each `filterType` provides a different set of operators in the filter drawer:
-
-| Type | Operators |
-|---|---|
-| `string` | contains, equals, does not equal, starts with, ends with, is set, is not set |
-| `status` | is, is not, is any of, is none of |
-| `boolean` | is |
-| `number` | equals, greater than, greater than or equal, less than, less than or equal |
-| `date` | is, after, before, on or after, on or before |
-
-## Extending existing tables
-
-Use the `tables` proxy to modify any registered table. Extensions must run **after** the table is registered (i.e., after the table definition file is imported).
-
-### Add a column
-
-```tsx
-import { tables } from '@/lib/table-registry'
-
-tables.products.addColumn({
- key: 'vendor',
- label: 'Vendor',
- sortable: true,
- filterable: true,
- default: true,
- render: (product) => product.vendor_name ?? '—',
-})
-```
-
-### Remove a column
-
-```tsx
-tables.products.removeColumn('inventory')
-```
-
-### Update a column
-
-Merges the updates into the existing column definition:
-
-```tsx
-tables.products.updateColumn('sku', {
- default: true, // make SKU visible by default
- label: 'Product SKU', // change the header label
-})
-```
-
-### Replace a column's renderer
-
-```tsx
-tables.products.updateColumn('name', {
- render: (product) => (
- <div className="flex items-center gap-2">
- <MyCustomAvatar src={product.thumbnail_url} />
- <span>{product.name}</span>
- </div>
- ),
-})
-```
-
-### Add a filter-only column
-
-Columns with `displayable: false` appear in the filter drawer but not in the table itself:
-
-```tsx
-tables.products.addColumn({
- key: 'in_stock',
- label: 'In Stock',
- filterable: true,
- filterType: 'boolean',
- displayable: false,
-})
-```
-
-## `<ResourceTable>` props
-
-| Prop | Type | Description |
-|---|---|---|
-| `tableKey` | `string` | Registry key matching the `defineTable()` call |
-| `queryKey` | `string` | TanStack Query cache key prefix |
-| `queryFn` | `(params) => Promise<{ data: T[], meta }>` | SDK call to fetch data. Receives pre-built Ransack params |
-| `searchParams` | `ResourceSearch` | Current URL search params from the route (use `Route.useSearch()`) |
-| `title` | `string` | Title displayed in the toolbar header. Overrides the table definition's `title` |
-| `actions` | `ReactNode` | Toolbar actions (e.g., "Add Product" button) |
-
-### URL state
-
-`<ResourceTable>` persists all table state in the URL via TanStack Router search params. The shared `resourceSearchSchema` validates these params:
-
-| Param | Type | Description |
-|---|---|---|
-| `page` | `number` | Current page (default: 1) |
-| `sort` | `string` | Sort field |
-| `dir` | `'asc' \| 'desc'` | Sort direction |
-| `search` | `string` | Search query |
-| `filters` | `string` (JSON) | Serialized `FilterRule[]` |
-| `columns` | `string` (comma-separated) | Visible column keys. Omitted when using defaults |
-
-Use `resourceSearchSchema` in your route's `validateSearch`:
-
-```tsx
-import { resourceSearchSchema } from '@/components/resource-table'
-
-export const Route = createFileRoute('/_authenticated/orders/')({
- validateSearch: resourceSearchSchema,
- component: OrdersPage,
-})
-```
-
-## How data fetching works
-
-`<ResourceTable>` builds the API params automatically:
-
-1. **Search** — sends `{ [searchParam]: value }` (e.g., `{ multi_search: "widget" }`)
-2. **Sort** — sends `{ sort: "field" }` or `{ sort: "-field" }` for descending
-3. **Filters** — converts each `FilterRule` to a Ransack param: `{ [ransackAttribute]_[operator]: value }` (e.g., `{ status_eq: "active" }`)
-4. **Pagination** — sends `{ page: N }`
-
-These params are passed to your `queryFn`, which forwards them to the SDK.
-
-## File structure
-
-```
-src/
- lib/
- table-registry.ts # defineTable, getTable, tables proxy
- formatters.ts # formatPrice, formatRelativeTime
- tables/
- products.tsx # Product table definition
- orders.tsx # Order table definition (example)
- components/
- resource-table.tsx # <ResourceTable> component + resourceSearchSchema
- table-toolbar.tsx # Search, filters, sort, column selector
- ui/
- data-table.tsx # Table primitives (Table, TableRow, etc.)
- pagination.tsx # Pagination component
- routes/
- _authenticated/
- products/
- index.tsx # Products list page (~30 lines)
- orders/
- index.tsx # Orders list page (~30 lines)
-```
-
-## Comparison with Rails admin
-
-| Rails Admin | React Admin |
-|---|---|
-| `Spree.admin.tables.register(:products, ...)` | `defineTable('products', { ... })` |
-| `Spree.admin.tables.products.add :name, ...` | Column in the `columns` array |
-| `type: :custom, partial: '...'` | `render: (row) => <Component />` |
-| `Spree.admin.tables.products.add :col, ...` (in initializer) | `tables.products.addColumn({ ... })` |
-| `Spree.admin.tables.products.remove :col` | `tables.products.removeColumn('col')` |
-| `Spree.admin.tables.products.update :col, ...` | `tables.products.updateColumn('col', { ... })` |
-| `render_table @collection, :products` | `<ResourceTable tableKey="products" ... />` |
-| `ransack_attribute: 'master_sku'` | `ransackAttribute: 'master_sku'` |
-| `filter_type: :status, value_options: [...]` | `filterType: 'status', filterOptions: [...]` |
-| `displayable: false` (filter-only) | `displayable: false` |
diff --git a/spree/api/ADMIN_API_PLAN.md b/spree/api/ADMIN_API_PLAN.md
deleted file mode 100644
index 3126f1781f..0000000000
--- a/spree/api/ADMIN_API_PLAN.md
+++ /dev/null
@@ -1,625 +0,0 @@
-# Admin API Implementation Plan and Conventions
-
-Admin API should include all the features and endpoints as the current Rails Admin in `spree/admin`.
-
-It should follow the same conventions and patterns as Store API.
-
-All controllers should inherit from `Spree::Api::V3::Admin::ResourceController`.
-
-API needs to be as much RESTful as possible, let's not make exceptions and not deviate from the pattern.
-
-The goal of building this API is to provide a programmatic interface for managing Spree resources. It will be available in SDK and CLI. Later we will build a new Admin Dashboard with Vite/TanStack on top of this API to replace our current Rails Admin.
-
-## Infrastructure (already built)
-
-The following infrastructure is already in place and ready for use:
-
-- **Base controllers:** `Spree::Api::V3::Admin::BaseController` and `Spree::Api::V3::Admin::ResourceController` — provide full CRUD, pagination (Pagy), Ransack filtering, CanCanCan authorization, prefixed ID lookups, and HTTP caching
-- **Authentication:** Secret API keys (`spree_sk_xxx`) via `authenticate_secret_key!` and JWT tokens with `admin_api` audience using `Spree.admin_user_class`
-- **Error handling:** Stripe-style error responses (see `docs/api-reference/store-api/errors.mdx`) — same format shared with Store API
-- **Serializers:** Admin serializers for 9 resources already exist in `api/app/serializers/spree/api/v3/admin/` (Product, Variant, Order, Customer, Price, Metafield, Taxon, Taxonomy, LineItem) — they extend their Store API counterparts with admin-only fields
-- **Dependency injection:** Admin serializers registered in `Spree::Api::Dependencies` (e.g., `Spree.api.admin_product_serializer`)
-- **Routes:** No admin API routes are defined yet — all routes need to be added to `api/config/routes.rb`
-
-## Serializers design
-
-Admin serializers should extend their Store API counterparts and add admin-only fields. It should include all fields/attributes for each model. This is admin API for power users who need to manage all aspects of the store.
-
-After each serializer change we need to run Typelizer to generate TypeScript types for the API.
-
-## Most important endpoints
-
-These endpoints will require special attention and careful design:
-
-* **Products API** — complex nested resource (variants, prices, images, option types, taxons); needs to support bulk operations
-* **Orders API** — deep nesting (line items, shipments, payments, refunds, adjustments, addresses); state machine transitions (cancel, approve, resume); special actions (resend confirmation)
-
-## Authentication
-
-We should follow Store API authentication conventions with a different JWT audience. Admin should use `Spree.admin_user_class` instead of `Spree.user_class`. JWT tokens should be short-lived.
-
-Two authentication methods are supported (infrastructure already exists):
-
-1. **Secret API keys** (`spree_sk_xxx`) — passed via `Authorization: Bearer spree_sk_xxx` header, verified with HMAC-SHA256 digest
-2. **JWT tokens** — generated via auth endpoint, passed via `Authorization: Bearer <token>` header, audience set to `admin_api`
-
-## Creating and updating resources
-
-We should follow Rails HTTP conventions for creating and updating resources, that is `POST` for creating and `PATCH` for updating. `DELETE` for deleting.
-
-It needs to support nested resources, eg. Product with variants.
-
-### Products
-
-Example product create/update params:
-
-```json
-{
- "name": "Test product",
- "tax_category_id": "taxcat_abc1234",
- "taxon_ids": [
- "taxon_abc123",
- "taxon_def456"
- ],
- "tags": [
- "eco",
- "best-seller"
- ],
- "variants": [
- {
- "option_type": "size",
- "option_value": "small",
- "total_on_hand": 10,
- "track_inventory": true,
- "width": 10.5,
- "height": 5.2,
- "depth": 2.1,
- "weight": 0.5,
- "dimensions_unit": "cm",
- "weight_unit": "kg",
- "prices": [
- {
- "currency": "USD",
- "amount": 10.99
- },
- {
- "currency": "EUR",
- "amount": 9.99
- }
- ]
- }
- ]
-}
-```
-
-If there are any validation errors, the API should return a `422 Unprocessable Entity` response with a JSON body containing the errors following the Stripe-style format:
-
-```json
-{
- "error": {
- "code": "validation_error",
- "message": "Name can't be blank",
- "details": {
- "name": ["can't be blank"]
- }
- }
-}
-```
-
-See `docs/api-reference/store-api/errors.mdx` for the full error conventions.
-
-We're not using Rails nested attributes, we use flat JSON objects for nested resources. Our main goal is to keep the API simple and easy to use for non-Rails developers (our target audience are TypeScript developers).
-
-### Orders
-
-Can create orders with line items in one API call.
-
-```json
-{
- "currency": "USD",
- "locale": "en-US",
- "line_items": [
- {
- "variant_id": "variant_123456789",
- "quantity": 1
- },
- {
- "variant_id": "variant_987654321",
- "quantity": 2
- }
- ]
-}
-```
-
-## Using services
-
-We should use existing services for business logic actions such as:
-* order create (`Spree.cart_create_service`)
-* order update (`Spree.order_update_service`)
-* line item create (`Spree.line_item_create_service`)
-* line item update (`Spree.line_item_update_service`)
-* product create (`Spree.product_create_service`) - new service needed
-* product update (`Spree.product_update_service`) - new service needed
-* etc
-
-Lets try not add new services besides the product create/update services. For other controllers/operations lets use standard record.update/create methods.
-
-If using service is needed we need to override create/update methods in the controller.
-
-## Scoping resources
-
-We need to scope resources to their parent, eg.
-
-```
-GET /api/v3/admin/products/prod_1234abc/variants/variant_123456789
-```
-
-Let's use the parent pattern already present in API v3.
-
-We should avoid 3-and-more-level nesting, as much as possible.
-
-## Ability to upload attachments
-
-We should support uploading attachments for resources, such as product images or order documents. Attachments should be uploaded using multipart/form-data.
-
-Attachments are stored in ActiveStorage. Special case is Product images which use a dedicated attachment model - `Spree::Asset` (which uses ActiveStorage under the hood but allows users to add `alt` and reorder the images and assign them to specific product variants).
-
-We should enforce max file size and type restrictions on attachments.
-
-## Response format
-
-All responses use flat JSON (no root key wrapping). Prefixed IDs are used everywhere (e.g., `prod_86Rf07xd4z`). Association IDs also use prefixed format.
-
-Filtering uses Ransack query params (e.g., `?q[name_cont]=shirt`). Sorting uses JSON:API format (e.g., `?sort=-created_at`).
-
-Associations can be expanded via `?expand=variants,variants.prices` (max 4 levels deep).
-
-## Testing
-
-Let's start with controller tests and don't do integration tests yet until we finalize the API design. For specific attributes testing we should use serializer tests and not controller tests.
-
-Tests should be lean, pragmatic and quick to run. Controller tests should cover known edge cases.
-
-## TODO
-
-Here's the endpoint list we need to implement:
-
-### Authentication
-- [ ] `POST /api/v3/admin/auth/login` — Admin user login (JWT token generation)
-- [ ] `POST /api/v3/admin/auth/refresh` — Refresh JWT token
-- [ ] `DELETE /api/v3/admin/auth/logout` — Invalidate JWT token
-
-### Products (⭐ high priority)
-- [x] `GET /api/v3/admin/products` — List products (with Ransack filtering, sorting, pagination)
-- [x] `GET /api/v3/admin/products/:id` — Show product
-- [x] `POST /api/v3/admin/products` — Create product (with nested variants, prices, taxon_ids)
-- [x] `PATCH /api/v3/admin/products/:id` — Update product
-- [x] `DELETE /api/v3/admin/products/:id` — Soft-delete product
-- [x] `POST /api/v3/admin/products/:id/clone` — Clone product
-- [ ] `PATCH /api/v3/admin/products/bulk_update` — Bulk update products (status, taxons, tags)
-
-### Variants (nested under Products)
-- [x] `GET /api/v3/admin/products/:product_id/variants` — List variants
-- [x] `GET /api/v3/admin/products/:product_id/variants/:id` — Show variant
-- [x] `POST /api/v3/admin/products/:product_id/variants` — Create variant (with nested prices)
-- [x] `PATCH /api/v3/admin/products/:product_id/variants/:id` — Update variant
-- [x] `DELETE /api/v3/admin/products/:product_id/variants/:id` — Soft-delete variant
-
-### Prices (managed via nested variant params, no standalone endpoints needed)
-
-### Product Assets (nested under Products)
-- [x] `GET /api/v3/admin/products/:product_id/assets` — List product assets (filterable by type: image, video, etc.)
-- [x] `POST /api/v3/admin/products/:product_id/assets` — Create asset. Two modes: (1) file upload via multipart/form-data, (2) URL via `source_url` param (triggers async download). Params: type, alt, position, variant_ids
-- [x] `PATCH /api/v3/admin/products/:product_id/assets/:id` — Update asset (alt, position, variant assignment)
-- [x] `DELETE /api/v3/admin/products/:product_id/assets/:id` — Delete asset
-
-### Digital Assets (nested under Products)
-- [ ] `GET /api/v3/admin/products/:product_id/digital_assets` — List digital assets
-- [ ] `POST /api/v3/admin/products/:product_id/digital_assets` — Upload digital asset
-- [ ] `PATCH /api/v3/admin/products/:product_id/digital_assets/:id` — Update digital asset
-- [ ] `DELETE /api/v3/admin/products/:product_id/digital_assets/:id` — Delete digital asset
-
-### Option Types
-- [x] `GET /api/v3/admin/option_types` — List option types
-- [x] `GET /api/v3/admin/option_types/:id` — Show option type
-- [x] `POST /api/v3/admin/option_types` — Create option type
-- [x] `PATCH /api/v3/admin/option_types/:id` — Update option type
-- [x] `DELETE /api/v3/admin/option_types/:id` — Delete option type
-
-### Option Values (nested under Option Types)
-- [x] `GET /api/v3/admin/option_types/:option_type_id/option_values` — List option values
-- [x] `POST /api/v3/admin/option_types/:option_type_id/option_values` — Create option value
-- [x] `PATCH /api/v3/admin/option_types/:option_type_id/option_values/:id` — Update option value
-- [x] `DELETE /api/v3/admin/option_types/:option_type_id/option_values/:id` — Delete option value
-
-### Taxonomies
-- [x] `GET /api/v3/admin/taxonomies` — List taxonomies
-- [x] `GET /api/v3/admin/taxonomies/:id` — Show taxonomy
-- [x] `POST /api/v3/admin/taxonomies` — Create taxonomy
-- [x] `PATCH /api/v3/admin/taxonomies/:id` — Update taxonomy
-- [x] `DELETE /api/v3/admin/taxonomies/:id` — Delete taxonomy
-
-### Taxons (nested under Taxonomies)
-- [x] `GET /api/v3/admin/taxonomies/:taxonomy_id/taxons` — List taxons
-- [x] `GET /api/v3/admin/taxonomies/:taxonomy_id/taxons/:id` — Show taxon
-- [x] `POST /api/v3/admin/taxonomies/:taxonomy_id/taxons` — Create taxon
-- [x] `PATCH /api/v3/admin/taxonomies/:taxonomy_id/taxons/:id` — Update taxon
-- [x] `DELETE /api/v3/admin/taxonomies/:taxonomy_id/taxons/:id` — Delete taxon
-- [x] `PATCH /api/v3/admin/taxonomies/:taxonomy_id/taxons/:id/reposition` — Reposition taxon in tree
-
-### Taxons (flat, top-level for convenience)
-- [x] `GET /api/v3/admin/taxons` — List all taxons across taxonomies
-- [x] `GET /api/v3/admin/taxons/:id` — Show taxon
-
-### Classifications (Product-Taxon assignments, nested under Taxons)
-- [ ] `GET /api/v3/admin/taxons/:taxon_id/classifications` — List products in taxon
-- [ ] `POST /api/v3/admin/taxons/:taxon_id/classifications` — Add product to taxon
-- [ ] `PATCH /api/v3/admin/taxons/:taxon_id/classifications/:id` — Update position
-- [ ] `DELETE /api/v3/admin/taxons/:taxon_id/classifications/:id` — Remove product from taxon
-
-### Orders (⭐ high priority)
-- [x] `GET /api/v3/admin/orders` — List orders (with Ransack filtering, sorting, pagination)
-- [x] `GET /api/v3/admin/orders/:id` — Show order
-- [x] `POST /api/v3/admin/orders` — Create draft order
-- [x] `PATCH /api/v3/admin/orders/:id` — Update order
-- [x] `DELETE /api/v3/admin/orders/:id` — Delete draft order
-- [x] `PATCH /api/v3/admin/orders/:id/next` — Push the order to the next state
-- [x] `PATCH /api/v3/admin/orders/:id/advance` — Advance the order to the furthest state
-- [x] `PATCH /api/v3/admin/orders/:id/complete` — Complete the order
-- [x] `PATCH /api/v3/admin/orders/:id/cancel` — Cancel order
-- [x] `PATCH /api/v3/admin/orders/:id/approve` — Approve order
-- [x] `PATCH /api/v3/admin/orders/:id/resume` — Resume canceled order
-- [x] `POST /api/v3/admin/orders/:id/resend_confirmation` — Resend confirmation email
-
-### Line Items (nested under Orders)
-- [x] `GET /api/v3/admin/orders/:order_id/line_items` — List line items
-- [x] `POST /api/v3/admin/orders/:order_id/line_items` — Add line item
-- [x] `PATCH /api/v3/admin/orders/:order_id/line_items/:id` — Update line item (quantity, price)
-- [x] `DELETE /api/v3/admin/orders/:order_id/line_items/:id` — Remove line item
-
-### Shipments (nested under Orders)
-- [x] `GET /api/v3/admin/orders/:order_id/shipments` — List shipments
-- [x] `GET /api/v3/admin/orders/:order_id/shipments/:id` — Show shipment
-- [ ] `POST /api/v3/admin/orders/:order_id/shipments` — Create shipment
-- [x] `PATCH /api/v3/admin/orders/:order_id/shipments/:id` — Update shipment
-- [x] `PATCH /api/v3/admin/orders/:order_id/shipments/:id/ship` — Mark shipment as shipped
-- [x] `PATCH /api/v3/admin/orders/:order_id/shipments/:id/cancel` — Cancel a shipment
-- [x] `PATCH /api/v3/admin/orders/:order_id/shipments/:id/resume` — Resume a canceled shipment
-- [x] `PATCH /api/v3/admin/orders/:order_id/shipments/:id/split` — Split/transfer items to a new shipment
-
-### Payments (nested under Orders)
-- [x] `GET /api/v3/admin/orders/:order_id/payments` — List payments
-- [x] `GET /api/v3/admin/orders/:order_id/payments/:id` — Show payment
-- [x] `POST /api/v3/admin/orders/:order_id/payments` — Create payment
-- [x] `PATCH /api/v3/admin/orders/:order_id/payments/:id/capture` — Capture payment
-- [x] `PATCH /api/v3/admin/orders/:order_id/payments/:id/void` — Void payment
-
-### Refunds (nested under Orders)
-- [x] `GET /api/v3/admin/orders/:order_id/refunds` — List refunds
-- [x] `POST /api/v3/admin/orders/:order_id/refunds` — Create refund (with payment_id in body)
-- [ ] `PATCH /api/v3/admin/orders/:order_id/refunds/:id` — Update refund
-
-### Adjustments (nested under Orders)
-- [x] `GET /api/v3/admin/orders/:order_id/adjustments` — List adjustments
-- [x] `POST /api/v3/admin/orders/:order_id/adjustments` — Create adjustment
-- [x] `PATCH /api/v3/admin/orders/:order_id/adjustments/:id` — Update adjustment
-- [x] `DELETE /api/v3/admin/orders/:order_id/adjustments/:id` — Delete adjustment
-
-### Order User Assignment
-- [ ] `PUT /api/v3/admin/orders/:order_id/user` — Assign user to order
-- [ ] `DELETE /api/v3/admin/orders/:order_id/user` — Remove user from order
-
-### Order Promotions
-- [ ] `POST /api/v3/admin/orders/:order_id/promotions` — Apply promotion to order (by promotion_id or coupon_code)
-- [ ] `DELETE /api/v3/admin/orders/:order_id/promotions/:id` — Remove promotion from order
-
-### Return Authorizations
-- [ ] `GET /api/v3/admin/return_authorizations` — List all return authorizations
-- [ ] `GET /api/v3/admin/orders/:order_id/return_authorizations` — List return authorizations for order
-- [ ] `GET /api/v3/admin/orders/:order_id/return_authorizations/:id` — Show return authorization
-- [ ] `POST /api/v3/admin/orders/:order_id/return_authorizations` — Create return authorization
-- [ ] `PATCH /api/v3/admin/orders/:order_id/return_authorizations/:id` — Update return authorization
-- [ ] `DELETE /api/v3/admin/return_authorizations/:id` — Delete return authorization
-- [ ] `PATCH /api/v3/admin/return_authorizations/:id/cancel` — Cancel return authorization
-
-### Customer Returns
-- [ ] `GET /api/v3/admin/customer_returns` — List all customer returns
-- [ ] `GET /api/v3/admin/orders/:order_id/customer_returns` — List customer returns for order
-- [ ] `POST /api/v3/admin/orders/:order_id/customer_returns` — Create customer return
-- [ ] `PATCH /api/v3/admin/orders/:order_id/customer_returns/:id` — Update customer return
-
-### Return Items
-- [ ] `PATCH /api/v3/admin/return_items/:id` — Update return item (reception status, acceptance status)
-
-### Reimbursements (nested under Orders)
-- [ ] `GET /api/v3/admin/orders/:order_id/reimbursements` — List reimbursements
-- [ ] `POST /api/v3/admin/orders/:order_id/reimbursements` — Create reimbursement
-- [ ] `PATCH /api/v3/admin/orders/:order_id/reimbursements/:id` — Update reimbursement
-- [ ] `DELETE /api/v3/admin/orders/:order_id/reimbursements/:id` — Delete reimbursement
-- [ ] `POST /api/v3/admin/orders/:order_id/reimbursements/:id/perform` — Perform reimbursement
-
-### Customers (Users)
-- [ ] `GET /api/v3/admin/customers` — List customers
-- [ ] `GET /api/v3/admin/customers/:id` — Show customer
-- [ ] `POST /api/v3/admin/customers` — Create customer
-- [ ] `PATCH /api/v3/admin/customers/:id` — Update customer
-- [ ] `DELETE /api/v3/admin/customers/:id` — Delete customer
-
-### Customer Addresses (nested under Customers)
-- [ ] `GET /api/v3/admin/customers/:customer_id/addresses` — List addresses
-- [ ] `POST /api/v3/admin/customers/:customer_id/addresses` — Create address
-- [ ] `PATCH /api/v3/admin/customers/:customer_id/addresses/:id` — Update address
-- [ ] `DELETE /api/v3/admin/customers/:customer_id/addresses/:id` — Delete address
-
-### Store Credits (nested under Customers)
-- [ ] `GET /api/v3/admin/customers/:customer_id/store_credits` — List store credits
-- [ ] `GET /api/v3/admin/customers/:customer_id/store_credits/:id` — Show store credit
-- [ ] `POST /api/v3/admin/customers/:customer_id/store_credits` — Create store credit
-- [ ] `PATCH /api/v3/admin/customers/:customer_id/store_credits/:id` — Update store credit
-- [ ] `DELETE /api/v3/admin/customers/:customer_id/store_credits/:id` — Delete store credit
-
-### Gift Cards
-- [ ] `GET /api/v3/admin/gift_cards` — List gift cards
-- [ ] `GET /api/v3/admin/gift_cards/:id` — Show gift card
-- [ ] `POST /api/v3/admin/gift_cards` — Create gift card
-- [ ] `PATCH /api/v3/admin/gift_cards/:id` — Update gift card
-- [ ] `DELETE /api/v3/admin/gift_cards/:id` — Delete gift card
-- [ ] `POST /api/v3/admin/gift_card_batches` — Batch create gift cards
-
-### Customer Groups
-- [ ] `GET /api/v3/admin/customer_groups` — List customer groups
-- [ ] `GET /api/v3/admin/customer_groups/:id` — Show customer group
-- [ ] `POST /api/v3/admin/customer_groups` — Create customer group
-- [ ] `PATCH /api/v3/admin/customer_groups/:id` — Update customer group
-- [ ] `DELETE /api/v3/admin/customer_groups/:id` — Delete customer group
-
-### Customer Group Members (nested under Customer Groups)
-- [ ] `GET /api/v3/admin/customer_groups/:customer_group_id/members` — List members
-- [ ] `POST /api/v3/admin/customer_groups/:customer_group_id/members` — Add members (bulk)
-- [ ] `DELETE /api/v3/admin/customer_groups/:customer_group_id/members/:id` — Remove member
-- [ ] `DELETE /api/v3/admin/customer_groups/:customer_group_id/members` — Remove members (bulk)
-
-### Newsletter Subscribers
-- [ ] `GET /api/v3/admin/newsletter_subscribers` — List subscribers
-- [ ] `DELETE /api/v3/admin/newsletter_subscribers/:id` — Delete subscriber
-
-### Promotions
-- [ ] `GET /api/v3/admin/promotions` — List promotions
-- [ ] `GET /api/v3/admin/promotions/:id` — Show promotion
-- [ ] `POST /api/v3/admin/promotions` — Create promotion
-- [ ] `PATCH /api/v3/admin/promotions/:id` — Update promotion
-- [ ] `DELETE /api/v3/admin/promotions/:id` — Delete promotion
-- [ ] `POST /api/v3/admin/promotions/:id/clone` — Clone promotion
-
-### Promotion Actions (nested under Promotions)
-- [ ] `GET /api/v3/admin/promotions/:promotion_id/actions` — List promotion actions
-- [ ] `POST /api/v3/admin/promotions/:promotion_id/actions` — Create promotion action
-- [ ] `PATCH /api/v3/admin/promotions/:promotion_id/actions/:id` — Update promotion action
-- [ ] `DELETE /api/v3/admin/promotions/:promotion_id/actions/:id` — Delete promotion action
-
-### Promotion Rules (nested under Promotions)
-- [ ] `GET /api/v3/admin/promotions/:promotion_id/rules` — List promotion rules
-- [ ] `POST /api/v3/admin/promotions/:promotion_id/rules` — Create promotion rule
-- [ ] `PATCH /api/v3/admin/promotions/:promotion_id/rules/:id` — Update promotion rule
-- [ ] `DELETE /api/v3/admin/promotions/:promotion_id/rules/:id` — Delete promotion rule
-
-### Coupon Codes (nested under Promotions, read-only)
-- [ ] `GET /api/v3/admin/promotions/:promotion_id/coupon_codes` — List coupon codes
-
-### Stock Locations
-- [ ] `GET /api/v3/admin/stock_locations` — List stock locations
-- [ ] `GET /api/v3/admin/stock_locations/:id` — Show stock location
-- [ ] `POST /api/v3/admin/stock_locations` — Create stock location
-- [ ] `PATCH /api/v3/admin/stock_locations/:id` — Update stock location
-- [ ] `DELETE /api/v3/admin/stock_locations/:id` — Delete stock location
-
-### Stock Items
-- [ ] `GET /api/v3/admin/stock_items` — List stock items (filterable by stock_location, variant)
-- [ ] `PATCH /api/v3/admin/stock_items/:id` — Update stock item (count_on_hand, backorderable)
-- [ ] `DELETE /api/v3/admin/stock_items/:id` — Delete stock item
-
-### Stock Transfers
-- [ ] `GET /api/v3/admin/stock_transfers` — List stock transfers
-- [ ] `GET /api/v3/admin/stock_transfers/:id` — Show stock transfer
-- [ ] `POST /api/v3/admin/stock_transfers` — Create stock transfer
-- [ ] `DELETE /api/v3/admin/stock_transfers/:id` — Delete stock transfer
-
-### Price Lists
-- [ ] `GET /api/v3/admin/price_lists` — List price lists
-- [ ] `GET /api/v3/admin/price_lists/:id` — Show price list
-- [ ] `POST /api/v3/admin/price_lists` — Create price list
-- [ ] `PATCH /api/v3/admin/price_lists/:id` — Update price list
-- [ ] `DELETE /api/v3/admin/price_lists/:id` — Delete price list
-
-### Price Rules (nested under Price Lists)
-- [ ] `GET /api/v3/admin/price_lists/:price_list_id/price_rules` — List price rules
-- [ ] `POST /api/v3/admin/price_lists/:price_list_id/price_rules` — Create price rule
-- [ ] `PATCH /api/v3/admin/price_lists/:price_list_id/price_rules/:id` — Update price rule
-- [ ] `DELETE /api/v3/admin/price_lists/:price_list_id/price_rules/:id` — Delete price rule
-
-### Price List Products (nested under Price Lists)
-- [ ] `GET /api/v3/admin/price_lists/:price_list_id/products` — List products in price list
-- [ ] `POST /api/v3/admin/price_lists/:price_list_id/products` — Add products to price list (bulk)
-- [ ] `DELETE /api/v3/admin/price_lists/:price_list_id/products` — Remove products from price list (bulk)
-
-### Payment Methods
-- [ ] `GET /api/v3/admin/payment_methods` — List payment methods
-- [ ] `GET /api/v3/admin/payment_methods/:id` — Show payment method
-- [ ] `POST /api/v3/admin/payment_methods` — Create payment method
-- [ ] `PATCH /api/v3/admin/payment_methods/:id` — Update payment method
-- [ ] `DELETE /api/v3/admin/payment_methods/:id` — Delete payment method
-
-### Shipping Methods
-- [ ] `GET /api/v3/admin/shipping_methods` — List shipping methods
-- [ ] `GET /api/v3/admin/shipping_methods/:id` — Show shipping method
-- [ ] `POST /api/v3/admin/shipping_methods` — Create shipping method
-- [ ] `PATCH /api/v3/admin/shipping_methods/:id` — Update shipping method
-- [ ] `DELETE /api/v3/admin/shipping_methods/:id` — Delete shipping method
-
-### Shipping Categories
-- [ ] `GET /api/v3/admin/shipping_categories` — List shipping categories
-- [ ] `GET /api/v3/admin/shipping_categories/:id` — Show shipping category
-- [ ] `POST /api/v3/admin/shipping_categories` — Create shipping category
-- [ ] `PATCH /api/v3/admin/shipping_categories/:id` — Update shipping category
-- [ ] `DELETE /api/v3/admin/shipping_categories/:id` — Delete shipping category
-
-### Tax Categories
-- [ ] `GET /api/v3/admin/tax_categories` — List tax categories
-- [ ] `GET /api/v3/admin/tax_categories/:id` — Show tax category
-- [ ] `POST /api/v3/admin/tax_categories` — Create tax category
-- [ ] `PATCH /api/v3/admin/tax_categories/:id` — Update tax category
-- [ ] `DELETE /api/v3/admin/tax_categories/:id` — Delete tax category
-
-### Tax Rates
-- [ ] `GET /api/v3/admin/tax_rates` — List tax rates
-- [ ] `GET /api/v3/admin/tax_rates/:id` — Show tax rate
-- [ ] `POST /api/v3/admin/tax_rates` — Create tax rate
-- [ ] `PATCH /api/v3/admin/tax_rates/:id` — Update tax rate
-- [ ] `DELETE /api/v3/admin/tax_rates/:id` — Delete tax rate
-
-### Zones
-- [ ] `GET /api/v3/admin/zones` — List zones
-- [ ] `GET /api/v3/admin/zones/:id` — Show zone
-- [ ] `POST /api/v3/admin/zones` — Create zone
-- [ ] `PATCH /api/v3/admin/zones/:id` — Update zone
-- [ ] `DELETE /api/v3/admin/zones/:id` — Delete zone
-
-### Markets
-- [ ] `GET /api/v3/admin/markets` — List markets
-- [ ] `GET /api/v3/admin/markets/:id` — Show market
-- [ ] `POST /api/v3/admin/markets` — Create market
-- [ ] `PATCH /api/v3/admin/markets/:id` — Update market
-- [ ] `DELETE /api/v3/admin/markets/:id` — Delete market
-
-### Countries
-- [ ] `GET /api/v3/admin/countries` — List countries
-- [ ] `GET /api/v3/admin/countries/:id` — Show country
-
-### Store Settings
-- [ ] `GET /api/v3/admin/store` — Get current store settings
-- [ ] `PATCH /api/v3/admin/store` — Update store settings
-
-### Policies
-- [ ] `GET /api/v3/admin/policies` — List policies
-- [ ] `GET /api/v3/admin/policies/:id` — Show policy
-- [ ] `POST /api/v3/admin/policies` — Create policy
-- [ ] `PATCH /api/v3/admin/policies/:id` — Update policy
-- [ ] `DELETE /api/v3/admin/policies/:id` — Delete policy
-
-### Admin Users
-- [ ] `GET /api/v3/admin/admin_users` — List admin users
-- [ ] `GET /api/v3/admin/admin_users/:id` — Show admin user
-- [ ] `POST /api/v3/admin/admin_users` — Create admin user
-- [ ] `PATCH /api/v3/admin/admin_users/:id` — Update admin user
-- [ ] `DELETE /api/v3/admin/admin_users/:id` — Delete admin user
-
-### Roles
-- [ ] `GET /api/v3/admin/roles` — List roles
-- [ ] `GET /api/v3/admin/roles/:id` — Show role
-- [ ] `POST /api/v3/admin/roles` — Create role
-- [ ] `PATCH /api/v3/admin/roles/:id` — Update role
-- [ ] `DELETE /api/v3/admin/roles/:id` — Delete role
-
-### Invitations
-- [ ] `GET /api/v3/admin/invitations` — List invitations
-- [ ] `POST /api/v3/admin/invitations` — Create invitation
-- [ ] `DELETE /api/v3/admin/invitations/:id` — Delete invitation
-- [ ] `PATCH /api/v3/admin/invitations/:id/resend` — Resend invitation
-
-### Metafield Definitions
-- [ ] `GET /api/v3/admin/metafield_definitions` — List metafield definitions
-- [ ] `GET /api/v3/admin/metafield_definitions/:id` — Show metafield definition
-- [ ] `POST /api/v3/admin/metafield_definitions` — Create metafield definition
-- [ ] `PATCH /api/v3/admin/metafield_definitions/:id` — Update metafield definition
-- [ ] `DELETE /api/v3/admin/metafield_definitions/:id` — Delete metafield definition
-
-### Metafields (polymorphic, nested under any resource)
-- [ ] `GET /api/v3/admin/:resource_type/:resource_id/metafields` — List metafields for resource
-- [ ] `POST /api/v3/admin/:resource_type/:resource_id/metafields` — Create metafield
-- [ ] `PATCH /api/v3/admin/:resource_type/:resource_id/metafields/:id` — Update metafield
-- [ ] `DELETE /api/v3/admin/:resource_type/:resource_id/metafields/:id` — Delete metafield
-
-### Translations (polymorphic, nested under any translatable resource)
-- [ ] `GET /api/v3/admin/:resource_type/:resource_id/translations` — List translations for resource
-- [ ] `PATCH /api/v3/admin/:resource_type/:resource_id/translations` — Update translations for resource
-
-### Tags
-- [ ] `GET /api/v3/admin/tags` — List tags
-- [ ] `POST /api/v3/admin/tags` — Create tag
-- [ ] `DELETE /api/v3/admin/tags/:id` — Delete tag
-
-### Refund Reasons
-- [ ] `GET /api/v3/admin/refund_reasons` — List refund reasons
-- [ ] `GET /api/v3/admin/refund_reasons/:id` — Show refund reason
-- [ ] `POST /api/v3/admin/refund_reasons` — Create refund reason
-- [ ] `PATCH /api/v3/admin/refund_reasons/:id` — Update refund reason
-- [ ] `DELETE /api/v3/admin/refund_reasons/:id` — Delete refund reason
-
-### Return Authorization Reasons
-- [ ] `GET /api/v3/admin/return_authorization_reasons` — List reasons
-- [ ] `GET /api/v3/admin/return_authorization_reasons/:id` — Show reason
-- [ ] `POST /api/v3/admin/return_authorization_reasons` — Create reason
-- [ ] `PATCH /api/v3/admin/return_authorization_reasons/:id` — Update reason
-- [ ] `DELETE /api/v3/admin/return_authorization_reasons/:id` — Delete reason
-
-### Store Credit Categories
-- [ ] `GET /api/v3/admin/store_credit_categories` — List categories
-- [ ] `GET /api/v3/admin/store_credit_categories/:id` — Show category
-- [ ] `POST /api/v3/admin/store_credit_categories` — Create category
-- [ ] `PATCH /api/v3/admin/store_credit_categories/:id` — Update category
-- [ ] `DELETE /api/v3/admin/store_credit_categories/:id` — Delete category
-
-### Reimbursement Types
-- [ ] `GET /api/v3/admin/reimbursement_types` — List types
-- [ ] `GET /api/v3/admin/reimbursement_types/:id` — Show type
-- [ ] `POST /api/v3/admin/reimbursement_types` — Create type
-- [ ] `PATCH /api/v3/admin/reimbursement_types/:id` — Update type
-- [ ] `DELETE /api/v3/admin/reimbursement_types/:id` — Delete type
-
-### Webhook Endpoints
-- [ ] `GET /api/v3/admin/webhook_endpoints` — List webhook endpoints
-- [ ] `GET /api/v3/admin/webhook_endpoints/:id` — Show webhook endpoint
-- [ ] `POST /api/v3/admin/webhook_endpoints` — Create webhook endpoint
-- [ ] `PATCH /api/v3/admin/webhook_endpoints/:id` — Update webhook endpoint
-- [ ] `DELETE /api/v3/admin/webhook_endpoints/:id` — Delete webhook endpoint
-
-### Webhook Deliveries (nested under Webhook Endpoints, read-only)
-- [ ] `GET /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries` — List deliveries
-- [ ] `GET /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id` — Show delivery
-
-### API Keys
-- [ ] `GET /api/v3/admin/api_keys` — List API keys
-- [ ] `POST /api/v3/admin/api_keys` — Create API key
-- [ ] `PATCH /api/v3/admin/api_keys/:id` — Update API key
-- [ ] `DELETE /api/v3/admin/api_keys/:id` — Delete API key
-- [ ] `PATCH /api/v3/admin/api_keys/:id/revoke` — Revoke API key
-
-### Integrations
-- [ ] `GET /api/v3/admin/integrations` — List integrations
-- [ ] `GET /api/v3/admin/integrations/:id` — Show integration
-- [ ] `POST /api/v3/admin/integrations` — Create integration
-- [ ] `PATCH /api/v3/admin/integrations/:id` — Update integration
-- [ ] `DELETE /api/v3/admin/integrations/:id` — Delete integration
-
-### Reports
-- [ ] `GET /api/v3/admin/reports` — List reports
-- [ ] `GET /api/v3/admin/reports/:id` — Show report
-- [ ] `POST /api/v3/admin/reports` — Create/generate report
-
-### Exports
-- [ ] `GET /api/v3/admin/exports` — List exports
-- [ ] `GET /api/v3/admin/exports/:id` — Show export (with download URL)
-- [ ] `POST /api/v3/admin/exports` — Create export
-
-### Imports
-- [ ] `GET /api/v3/admin/imports` — List imports
-- [ ] `GET /api/v3/admin/imports/:id` — Show import (with status, row counts)
-- [ ] `POST /api/v3/admin/imports` — Create import (multipart/form-data)
-- [ ] `PATCH /api/v3/admin/imports/:id/complete_mapping` — Complete field mapping and start import
-
-### Dashboard
-- [ ] `GET /api/v3/admin/dashboard/analytics` — Get dashboard analytics data
-
-**Total: 296 endpoints**
-
-After implementing each endpoint please mark it as done on the list above.