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.

Update 6.0 Admin API plan: mark shipped endpoints, resolve bulk ops (#14223)

Damian Legawiecb23a6594334d
diff --git a/docs/plans/6.0-admin-api.md b/docs/plans/6.0-admin-api.md
index b4551083c0..c3ce9d57e4 100644
--- a/docs/plans/6.0-admin-api.md
+++ b/docs/plans/6.0-admin-api.md
@@ -4,7 +4,7 @@
**Target:** Spree 6.0
**Depends on:** `6.0-admin-spa.md`, `6.0-platform-auth.md`
**Author:** damian
-**Last updated:** 2026-04-11
+**Last updated:** 2026-06-25
## Summary
@@ -139,22 +139,22 @@ Per-record conditions (CanCanCan blocks/hashes) are not serialized — only `has
### 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.
+- Base controllers, resource controller, admin authentication, JWT with admin audience, secret API key auth (with [scopes](5.5-admin-api-key-scopes.md)), httpOnly refresh-cookie auth, prefixed IDs, error handling, Pagy, Ransack, CanCanCan scoping, per-action bulk-operation helper (`Spree::Api::V3::BulkOperations`), `custom_fieldable` route concern, Active Storage direct uploads — all in place.
+- Admin serializers exist for Product, Variant, Price, PriceList, Order, LineItem, Fulfillment, Payment, Refund, Adjustment, Customer, Address, CreditCard, StoreCredit, CustomerGroup, GiftCard, GiftCardBatch, Category, OptionType, OptionValue, Promotion, PromotionAction, PromotionRule, CouponCode, PaymentMethod, Channel, Market, Country, TaxCategory, StockLocation, StockItem, StockReservation, StockTransfer, Store, AdminUser, Role, Invitation, ApiKey, AllowedOrigin, WebhookEndpoint, WebhookDelivery, Export, CustomFieldDefinition, CustomField, Tag, StoreCreditCategory. 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**
+1. **Authentication** — login, refresh, logout, me ✅
+2. **Products + Variants + Media + Options** — highest-priority, hardest, nested ✅
+3. **Orders + Items + Fulfillments + Payments + Adjustments + Refunds** ✅
+4. **Customers + Addresses + Credit Cards + Store Credits + Customer Groups + Gift Cards** ✅
+5. **Promotions + Rules + Actions + Coupon Codes** ✅
+6. **Stock (Locations, Items, Reservations, Transfers) + Price Lists + Prices** ✅ (Transfers lifecycle + Vendors + Purchase Orders pending — see `6.0-inventory-operations.md`)
+7. **Categories** ✅ (read) — Collections + write/reposition pending
+8. **Store settings ✅, Channels ✅, Markets ✅, Tax Categories ✅, Admin users ✅, Roles ✅ (read), Invitations ✅, API keys ✅, Webhooks ✅, Allowed Origins ✅, Exports ✅, Dashboard ✅**; Policies pending
+9. **Custom Fields + Custom Field Definitions** ✅ — Translations (polymorphic) pending
+10. **Returns/Exchanges/Claims, Product Types, Collections, Catalogs/Companies (B2B), Delivery Methods/Zones, Tax Rates/Markets-as-tax, Payment Methods ✅** — remaining 6.0 model work
+11. **Reports, Imports, Integrations, Price History, Stock Movements** — pending
### PR process for each endpoint
@@ -264,10 +264,15 @@ Also tracked in the SDK type definitions. See each linked plan for rationale.
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] `POST /api/v3/admin/auth/login` — admin user login (JWT + httpOnly refresh cookie)
+- [x] `POST /api/v3/admin/auth/refresh` — rotate refresh token (read from signed cookie), return new JWT
+- [x] `POST /api/v3/admin/auth/logout` — invalidate JWT and refresh token, clear cookie
- [x] `GET /api/v3/admin/me` — current admin user + serialized permissions
+- [x] `PATCH /api/v3/admin/me` — self-service profile updates (e.g. the admin's own UI language)
+- [x] `GET /api/v3/admin/auth/invitations/:id/lookup` — public invitation lookup (prefixed ID + token in URL act as credential)
+- [x] `POST /api/v3/admin/auth/invitations/:id/accept` — public invitation acceptance (sets password, issues tokens)
+
+> **5.x → 6.0:** Logout shipped as `POST` (not `DELETE`); the refresh token moved to an httpOnly signed cookie and is no longer returned in the login response body. See `5.5-admin-auth-cookie-refresh.md`, `6.0-platform-auth.md`.
### Products (⭐ high priority)
- [x] `GET /api/v3/admin/products` — list (Ransack, sort, paginate)
@@ -276,7 +281,13 @@ Each endpoint below is tracked as `[ ]` (pending) or `[x]` (shipped). When you i
- [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
+- [x] `POST /api/v3/admin/products/bulk_status_update` — bulk status change
+- [x] `POST /api/v3/admin/products/bulk_add_to_categories` / `bulk_remove_from_categories`
+- [x] `POST /api/v3/admin/products/bulk_add_to_channels` / `bulk_remove_from_channels`
+- [x] `POST /api/v3/admin/products/bulk_add_tags` / `bulk_remove_tags`
+- [x] `DELETE /api/v3/admin/products/bulk_destroy`
+
+> **Bulk envelope decision (resolved):** per-action bulk routes (not a single `/bulk`), bodies `{ ids: [...], ... }`, shared via the `Spree::Api::V3::BulkOperations` concern. Resolves the "Bulk operations envelope" open question.
> **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`).
@@ -287,14 +298,28 @@ Each endpoint below is tracked as `[ ]` (pending) or `[x]` (shipped). When you i
- [x] `PATCH /api/v3/admin/products/:product_id/variants/:id`
- [x] `DELETE /api/v3/admin/products/:product_id/variants/:id`
+### Variants (top-level — search / autocomplete across all products)
+- [x] `GET /api/v3/admin/variants` — flat variant search (e.g. order line-item picker); supports `custom_fields`
+- [x] `GET /api/v3/admin/variants/:id`
+
### Prices
-Managed via nested variant params — no standalone endpoints.
+A standalone `Spree::Price` resource covers **both** base prices (`price_list_id: nil`) **and** price-list overrides, filtered via Ransack on index. (Variant create/update may still set prices inline via nested params, but prices are independently addressable.)
+- [x] `GET /api/v3/admin/prices` — list (filter by variant, currency, price_list)
+- [x] `GET /api/v3/admin/prices/:id`
+- [x] `POST /api/v3/admin/prices`
+- [x] `PATCH /api/v3/admin/prices/:id`
+- [x] `DELETE /api/v3/admin/prices/:id` — soft delete
+- [x] `POST /api/v3/admin/prices/bulk_upsert` — upsert on `(variant_id, currency, price_list_id)`
+- [x] `DELETE /api/v3/admin/prices/bulk_destroy`
### 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] `PATCH /api/v3/admin/products/:product_id/media/:id` — update alt, position, variant assignment (`variant_ids: []`)
- [x] `DELETE /api/v3/admin/products/:product_id/media/:id`
+- [x] `GET|POST /api/v3/admin/products/:product_id/variants/:variant_id/media` + `PATCH|DELETE .../media/:id` — variant-level media (legacy path retained in 5.5)
+
+> **6.0:** Media defaults to `viewable_type: 'Spree::Product'`; variant↔product-asset linking via the `variant_ids` array (`Spree::VariantMedia` join). `expand=images` → `expand=media`. See `5.4-6.0-product-media-system.md`.
### Digital Assets (nested under Products)
- [ ] `GET /api/v3/admin/products/:product_id/digital_assets`
@@ -309,11 +334,8 @@ Managed via nested variant params — no standalone endpoints.
- [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`
+### Option Values
+Managed via nested payload on the Option Type (`option_values: [{ id, name, label, position, color_code, image, _destroy }]`) — no standalone endpoints. Position drives drag-and-drop reorder; `kind` (`dropdown`/`color_swatch`/`buttons`) lives on the Option Type and `color_code`/`image` on each value. See `5.4-option-type-enhancements.md`.
### Product Types (renamed from Prototypes)
- [ ] `GET /api/v3/admin/product_types`
@@ -349,20 +371,19 @@ Managed via nested variant params — no standalone endpoints.
> **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`
+### Channels (new in 6.0) — shipped 5.5
+- [x] `GET /api/v3/admin/channels`
+- [x] `GET /api/v3/admin/channels/:id`
+- [x] `POST /api/v3/admin/channels`
+- [x] `PATCH /api/v3/admin/channels/:id`
+- [x] `DELETE /api/v3/admin/channels/:id`
+- [x] `POST /api/v3/admin/channels/:id/add_products` — bulk publish (`product_ids`, optional `published_at`/`unpublished_at`)
+- [x] `POST /api/v3/admin/channels/:id/remove_products` — bulk unpublish (`product_ids`)
-> **6.0:** A Channel is a sales surface (POS, Storefront A, Marketplace, etc.). See `6.0-channels-catalogs-b2b.md`.
+> **6.0:** A Channel is a sales surface (POS, Storefront A, Marketplace, etc.). `Channel#default` resolves the store's default channel. See `6.0-channels-catalogs-b2b.md`, `6.0-order-routing.md`.
-### Product Listings (nested under Channels, replaces StoreProduct)
-- [ ] `GET /api/v3/admin/channels/:channel_id/product_publications`
-- [ ] `POST /api/v3/admin/channels/:channel_id/product_publications`
-- [ ] `DELETE /api/v3/admin/channels/:channel_id/product_publications/:id`
-- [ ] `POST /api/v3/admin/channels/:channel_id/product_publications/bulk` — bulk add/remove
+### Product Publications (replaces StoreProduct)
+**Nested `product_publications` CRUD was cut** — the SPA never used it and there's no industry precedent. Publication is managed through Channel member actions (`/channels/:id/add_products`, `/remove_products`) and the product-side bulk routes (`/products/bulk_add_to_channels`, `/products/bulk_remove_from_channels`). See `6.0-channels-catalogs-b2b.md`.
### Catalogs (new in 6.0, B2B)
- [ ] `GET /api/v3/admin/catalogs`
@@ -512,50 +533,61 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/:id`
> **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`
+### Customers (users) — shipped 5.5
+- [x] `GET /api/v3/admin/customers`
+- [x] `GET /api/v3/admin/customers/:id`
+- [x] `POST /api/v3/admin/customers`
+- [x] `PATCH /api/v3/admin/customers/:id`
+- [x] `DELETE /api/v3/admin/customers/:id`
+- [x] `POST /api/v3/admin/customers/bulk_add_to_groups` / `bulk_remove_from_groups`
+- [x] `POST /api/v3/admin/customers/bulk_add_tags` / `bulk_remove_tags`
+- [ ] `POST /api/v3/admin/customers/:id/anonymize` — GDPR right to erasure (Phase 2)
+- [ ] `GET /api/v3/admin/customers/:id/export` — GDPR data export, returns JSON download URL (Phase 2)
+
+> **6.0:** `Spree.user_class` → `Spree.customer_class`. `Spree::LegacyUser` → `Spree::Customer`. Customers + nested addresses/credit_cards/store_credits + CustomerGroups shipped in 5.5 (`5.5-admin-customers-api.md`). Anonymize + export endpoints are Phase 2 GDPR (`5.4-6.0-eu-legal-compliance.md`); customer group membership is managed via the customer bulk routes above, not nested `members` endpoints.
+
+### Customer Addresses (nested under Customers) — shipped 5.5
+- [x] `GET /api/v3/admin/customers/:customer_id/addresses`
+- [x] `GET /api/v3/admin/customers/:customer_id/addresses/:id`
+- [x] `POST /api/v3/admin/customers/:customer_id/addresses`
+- [x] `PATCH /api/v3/admin/customers/:customer_id/addresses/:id`
+- [x] `DELETE /api/v3/admin/customers/:customer_id/addresses/:id`
+
+> Default-address handling via `is_default_billing` / `is_default_shipping` flags on the address PATCH (rotates the previous default in a transaction) — no separate FK write target.
+
+### Customer Credit Cards (nested under Customers, read + delete) — shipped 5.5
+- [x] `GET /api/v3/admin/customers/:customer_id/credit_cards`
+- [x] `GET /api/v3/admin/customers/:customer_id/credit_cards/:id`
+- [x] `DELETE /api/v3/admin/customers/:customer_id/credit_cards/:id`
+
+> No create/update — cards are tokenized through the storefront/SCA flow; admin can only view and remove them. `cc_type` → `brand`, `last_digits` → `last4`.
+
+### Store Credits (nested under Customers) — shipped 5.5
+- [x] `GET /api/v3/admin/customers/:customer_id/store_credits`
+- [x] `GET /api/v3/admin/customers/:customer_id/store_credits/:id`
+- [x] `POST /api/v3/admin/customers/:customer_id/store_credits`
+- [x] `PATCH /api/v3/admin/customers/:customer_id/store_credits/:id`
+- [x] `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
+- [x] `GET /api/v3/admin/gift_cards`
+- [x] `GET /api/v3/admin/gift_cards/:id`
+- [x] `POST /api/v3/admin/gift_cards`
+- [x] `PATCH /api/v3/admin/gift_cards/:id`
+- [x] `DELETE /api/v3/admin/gift_cards/:id`
+- [x] `GET /api/v3/admin/gift_card_batches`
+- [x] `GET /api/v3/admin/gift_card_batches/:id`
+- [x] `POST /api/v3/admin/gift_card_batches` — batch create
+
+### Customer Groups — shipped 5.5
+- [x] `GET /api/v3/admin/customer_groups`
+- [x] `GET /api/v3/admin/customer_groups/:id`
+- [x] `POST /api/v3/admin/customer_groups`
+- [x] `PATCH /api/v3/admin/customer_groups/:id`
+- [x] `DELETE /api/v3/admin/customer_groups/:id`
+
+### Customer Group Members
+**Nested `members` CRUD was not built** — membership is managed from the customer side via `POST /api/v3/admin/customers/bulk_add_to_groups` / `bulk_remove_from_groups` (body: `{ ids: [...], customer_group_ids: [...] }`). Group contents are read via `GET /api/v3/admin/customers?q[customer_group_members_customer_group_id_eq]=...`.
### Newsletter Subscribers
- [ ] `GET /api/v3/admin/newsletter_subscribers`
@@ -568,27 +600,33 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/: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`
+- [x] `GET /api/v3/admin/promotions`
+- [x] `GET /api/v3/admin/promotions/:id`
+- [x] `POST /api/v3/admin/promotions`
+- [x] `PATCH /api/v3/admin/promotions/:id`
+- [x] `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`
+- [x] `GET /api/v3/admin/promotions/:promotion_id/promotion_actions`
+- [x] `GET /api/v3/admin/promotions/:promotion_id/promotion_actions/:id`
+- [x] `POST /api/v3/admin/promotions/:promotion_id/promotion_actions`
+- [x] `PATCH /api/v3/admin/promotions/:promotion_id/promotion_actions/:id`
+- [x] `DELETE /api/v3/admin/promotions/:promotion_id/promotion_actions/:id`
+- [x] `GET /api/v3/admin/promotion_actions/types` — registered action subclasses + preference schemas (for the "Add action" picker)
+- [x] `GET /api/v3/admin/promotion_actions/calculators` — registered calculator subclasses + preference schemas for `CalculatedAdjustments` actions
### 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`
+- [x] `GET /api/v3/admin/promotions/:promotion_id/promotion_rules`
+- [x] `GET /api/v3/admin/promotions/:promotion_id/promotion_rules/:id`
+- [x] `POST /api/v3/admin/promotions/:promotion_id/promotion_rules`
+- [x] `PATCH /api/v3/admin/promotions/:promotion_id/promotion_rules/:id`
+- [x] `DELETE /api/v3/admin/promotions/:promotion_id/promotion_rules/:id`
+- [x] `GET /api/v3/admin/promotion_rules/types` — registered rule subclasses + preference schemas (for the "Add rule" picker)
### Coupon Codes (nested under Promotions, read-only)
-- [ ] `GET /api/v3/admin/promotions/:promotion_id/coupon_codes`
+- [x] `GET /api/v3/admin/promotions/:promotion_id/coupon_codes`
+- [x] `GET /api/v3/admin/promotions/:promotion_id/coupon_codes/:id`
### Stock Locations
- [x] `GET /api/v3/admin/stock_locations`
@@ -598,9 +636,10 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/:id`
- [x] `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`
+- [x] `GET /api/v3/admin/stock_items` — filterable by stock_location, variant
+- [x] `GET /api/v3/admin/stock_items/:id`
+- [x] `PATCH /api/v3/admin/stock_items/:id`
+- [x] `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`
@@ -608,34 +647,57 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/: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
+- [x] `GET /api/v3/admin/stock_reservations` — filterable by variant, order, cart
+- [x] `GET /api/v3/admin/stock_reservations/:id`
- [ ] `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`
+- [x] `GET /api/v3/admin/stock_transfers`
+- [x] `GET /api/v3/admin/stock_transfers/:id`
+- [x] `POST /api/v3/admin/stock_transfers`
+- [x] `DELETE /api/v3/admin/stock_transfers/:id` — draft only
+- [ ] `PATCH /api/v3/admin/stock_transfers/:id`
+- [ ] `POST /api/v3/admin/stock_transfers/:id/mark_ready`
+- [ ] `POST /api/v3/admin/stock_transfers/:id/mark_in_transit`
+- [ ] `POST /api/v3/admin/stock_transfers/:id/receive` — body `{ items: [{ id, quantity_received, discrepancy_reason }] }` (partial receive)
+- [ ] `POST /api/v3/admin/stock_transfers/:id/cancel`
+
+> **6.0:** Transfer lifecycle (draft → ready_to_ship → in_transit → received) + partial receive are pending. See `6.0-inventory-operations.md`.
+
+### Vendors (new in 6.0)
+- [ ] `GET /api/v3/admin/vendors`
+- [ ] `GET /api/v3/admin/vendors/:id`
+- [ ] `POST /api/v3/admin/vendors`
+- [ ] `PATCH /api/v3/admin/vendors/:id`
+- [ ] `DELETE /api/v3/admin/vendors/:id`
+
+### Purchase Orders (new in 6.0)
+- [ ] `GET /api/v3/admin/purchase_orders`
+- [ ] `GET /api/v3/admin/purchase_orders/:id`
+- [ ] `POST /api/v3/admin/purchase_orders`
+- [ ] `PATCH /api/v3/admin/purchase_orders/:id`
+- [ ] `DELETE /api/v3/admin/purchase_orders/:id` — draft only
+- [ ] `POST /api/v3/admin/purchase_orders/:id/mark_ordered`
+- [ ] `POST /api/v3/admin/purchase_orders/:id/receive` — body `{ items: [{ id, quantity_received }] }`
+- [ ] `POST /api/v3/admin/purchase_orders/:id/cancel`
+
+> **6.0:** `Spree::PurchaseOrder` + `Spree::Vendor` replace today's "external receive" hack. See `6.0-inventory-operations.md`.
### 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
+- [x] `GET /api/v3/admin/price_lists`
+- [x] `GET /api/v3/admin/price_lists/:id`
+- [x] `POST /api/v3/admin/price_lists`
+- [x] `PATCH /api/v3/admin/price_lists/:id` — saves name/schedule/match policy + `product_ids: []` + nested `rules: []` + `prices: []` in one round-trip
+- [x] `DELETE /api/v3/admin/price_lists/:id`
+- [x] `PATCH /api/v3/admin/price_lists/:id/activate` — draft|inactive → active (or scheduled when `starts_at` is in the future)
+- [x] `PATCH /api/v3/admin/price_lists/:id/deactivate`
+- [x] `GET /api/v3/admin/price_lists/:id/prices` — spreadsheet data feed (filter by `?currency=`)
+- [x] `GET /api/v3/admin/price_lists/price_rule_types` — registered rule subclasses + preference schemas (for the "Add rule" picker)
+
+### Price Rules / Price List Products
+**No standalone nested endpoints.** Price-list rules ride along on the price list's PATCH body (`rules: [{ id, type, preferences }]`); product membership rides along as `product_ids: [...]`. Individual price overrides flow through the standalone `/prices` resource (or the price list's `prices: []` payload). See the Prices section above.
### 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"
@@ -643,11 +705,12 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/:id`
> **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`
+- [x] `GET /api/v3/admin/payment_methods`
+- [x] `GET /api/v3/admin/payment_methods/:id`
+- [x] `POST /api/v3/admin/payment_methods`
+- [x] `PATCH /api/v3/admin/payment_methods/:id`
+- [x] `DELETE /api/v3/admin/payment_methods/:id`
+- [x] `GET /api/v3/admin/payment_methods/types` — registered gateway subclasses + preference schemas (for the "Add payment method" picker)
### Delivery Methods (replaces Shipping Methods)
- [ ] `GET /api/v3/admin/delivery_methods`
@@ -673,9 +736,9 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/: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`
+- [x] `POST /api/v3/admin/tax_categories`
+- [x] `PATCH /api/v3/admin/tax_categories/:id`
+- [x] `DELETE /api/v3/admin/tax_categories/:id`
### Tax Rates
- [ ] `GET /api/v3/admin/tax_rates`
@@ -687,15 +750,15 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/: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`
+- [x] `GET /api/v3/admin/markets`
+- [x] `GET /api/v3/admin/markets/:id`
+- [x] `POST /api/v3/admin/markets`
+- [x] `PATCH /api/v3/admin/markets/:id`
+- [x] `DELETE /api/v3/admin/markets/:id`
### Countries
-- [ ] `GET /api/v3/admin/countries`
-- [ ] `GET /api/v3/admin/countries/:id`
+- [x] `GET /api/v3/admin/countries` — supports `?expand=states` for state/province dropdowns
+- [x] `GET /api/v3/admin/countries/:id`
### Store Settings
- [x] `GET /api/v3/admin/store`
@@ -709,51 +772,73 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/: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`
+- [x] `GET /api/v3/admin/admin_users`
+- [x] `GET /api/v3/admin/admin_users/:id`
+- [x] `PATCH /api/v3/admin/admin_users/:id`
+- [x] `DELETE /api/v3/admin/admin_users/:id`
+> **No `POST /admin_users`** — admin users are created by accepting an invitation (`/auth/invitations/:id/accept`), not by direct creation.
> **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`
+- [x] `GET /api/v3/admin/roles` — read-only (feeds role pickers on invitations + admin users)
+- [x] `GET /api/v3/admin/roles/:id`
- [ ] `POST /api/v3/admin/roles`
- [ ] `PATCH /api/v3/admin/roles/:id`
- [ ] `DELETE /api/v3/admin/roles/:id`
+> Custom-role CRUD is deferred; roles are currently seeded/predefined and exposed read-only.
+
### Invitations
-- [ ] `GET /api/v3/admin/invitations`
-- [ ] `POST /api/v3/admin/invitations`
-- [ ] `DELETE /api/v3/admin/invitations/:id`
-- [ ] `PATCH /api/v3/admin/invitations/:id/resend`
+- [x] `GET /api/v3/admin/invitations`
+- [x] `GET /api/v3/admin/invitations/:id`
+- [x] `POST /api/v3/admin/invitations`
+- [x] `DELETE /api/v3/admin/invitations/:id`
+- [x] `PATCH /api/v3/admin/invitations/:id/resend`
+
+> Public acceptance endpoints (`GET/POST /auth/invitations/:id/...`) live under Authentication above.
+
+### Allowed Origins (CORS allowlist)
+- [x] `GET /api/v3/admin/allowed_origins`
+- [x] `GET /api/v3/admin/allowed_origins/:id`
+- [x] `POST /api/v3/admin/allowed_origins`
+- [x] `PATCH /api/v3/admin/allowed_origins/:id`
+- [x] `DELETE /api/v3/admin/allowed_origins/:id`
+
+### Direct Uploads (Active Storage)
+- [x] `POST /api/v3/admin/direct_uploads` — pre-signed blob upload helper for media/import attachments
### 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`
+- [x] `GET /api/v3/admin/custom_field_definitions`
+- [x] `GET /api/v3/admin/custom_field_definitions/:id`
+- [x] `POST /api/v3/admin/custom_field_definitions`
+- [x] `PATCH /api/v3/admin/custom_field_definitions/:id`
+- [x] `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`
+### Custom Fields (nested under each custom-fieldable resource)
+Mounted via the `custom_fieldable` route concern — `custom_fields` is nested under each parent that includes `Spree::Metafields`, **not** a single flat `/:resource_type/:resource_id/custom_fields` route. Resolves the "Polymorphic custom fields routing" open question.
+- [x] `GET|POST /api/v3/admin/products/:product_id/custom_fields` + `PATCH|DELETE .../custom_fields/:id`
+- [x] `…/variants/:variant_id/custom_fields`
+- [x] `…/categories/:category_id/custom_fields`
+- [x] `…/option_types/:option_type_id/custom_fields`
+- [x] `…/customers/:customer_id/custom_fields`
+- [x] `…/orders/:order_id/custom_fields`
+
+> New parents get custom-field endpoints for free by adding `concerns: :custom_fieldable` to their route + including `Spree::Metafields` on the model.
### 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`
+- [x] `GET /api/v3/admin/tags` — autocomplete for product/order/customer tag inputs
- [ ] `POST /api/v3/admin/tags`
- [ ] `DELETE /api/v3/admin/tags/:id`
+> Tags are created/removed implicitly through their taggable resources (e.g. `products/bulk_add_tags`, the `tags: []` param on a product). Standalone create/destroy is not exposed.
+
### Refund Reasons
- [ ] `GET /api/v3/admin/refund_reasons`
- [ ] `GET /api/v3/admin/refund_reasons/:id`
@@ -769,29 +854,36 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/: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`
+- [x] `GET /api/v3/admin/store_credit_categories` — read-only (feeds the store-credit category dropdown)
+- [x] `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`
+- [x] `GET /api/v3/admin/webhook_endpoints`
+- [x] `GET /api/v3/admin/webhook_endpoints/:id`
+- [x] `POST /api/v3/admin/webhook_endpoints`
+- [x] `PATCH /api/v3/admin/webhook_endpoints/:id`
+- [x] `DELETE /api/v3/admin/webhook_endpoints/:id`
+- [x] `POST /api/v3/admin/webhook_endpoints/:id/send_test` — fire a test delivery
+- [x] `PATCH /api/v3/admin/webhook_endpoints/:id/enable` / `disable`
### 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`
+- [x] `GET /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries`
+- [x] `GET /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id`
+- [x] `POST /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id/redeliver`
### 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`
+- [x] `GET /api/v3/admin/api_keys`
+- [x] `GET /api/v3/admin/api_keys/:id`
+- [x] `GET /api/v3/admin/api_keys/current` — the key the request authenticated with
+- [x] `POST /api/v3/admin/api_keys`
+- [x] `PATCH /api/v3/admin/api_keys/:id`
+- [x] `DELETE /api/v3/admin/api_keys/:id`
+- [x] `PATCH /api/v3/admin/api_keys/:id/revoke`
+
+> Keys carry Shopify-style `read_*`/`write_*` scopes. See `5.5-admin-api-key-scopes.md`.
### Integrations
- [ ] `GET /api/v3/admin/integrations`
@@ -808,9 +900,13 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/: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`
+- [x] `GET /api/v3/admin/exports`
+- [x] `GET /api/v3/admin/exports/:id` — includes `done`, `download_url`, `filename`, `byte_size`
+- [x] `POST /api/v3/admin/exports` — type `Spree::Exports::{Products,Orders,Customers}` + optional `search_params` / `record_selection`
+- [x] `DELETE /api/v3/admin/exports/:id`
+- [x] `GET /api/v3/admin/exports/:id/download` — redirect to the generated file
+
+> No `PATCH` — exports are immutable once created. See `5.5-admin-spa-csv-export.md`.
### Imports
- [ ] `GET /api/v3/admin/imports`
@@ -819,14 +915,18 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/:id`
- [ ] `PATCH /api/v3/admin/imports/:id/complete_mapping`
### Dashboard
-- [ ] `GET /api/v3/admin/dashboard/analytics`
+- [x] `GET /api/v3/admin/dashboard/analytics`
+
+## Resolved Questions
+
+- **Bulk operations envelope** — ✅ resolved: per-action bulk routes (`bulk_status_update`, `bulk_add_to_categories`, `bulk_add_to_channels`, `bulk_add_tags`, `bulk_destroy`, `prices/bulk_upsert`, `customers/bulk_add_to_groups`, …), bodies `{ ids: [...], ... }`, shared via the `Spree::Api::V3::BulkOperations` concern. No single `/bulk` envelope.
+- **Order customer assignment** — ✅ resolved: `PATCH /orders/:id { customer_id }` (5.x bridge also accepts `user_id`). No dedicated sub-resource.
+- **Polymorphic custom fields routing** — ✅ resolved: `custom_fields` mounted via the `custom_fieldable` route concern under each parent resource, not a flat `/:resource_type/:resource_id/custom_fields` route.
## 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?
+- **Translations endpoint** — one PATCH for all locales vs. one PATCH per locale? Still open; the polymorphic translations endpoints are not yet built. See `5.4-centralized-translations-admin.md`, `5.4-metafield-translations.md`.
+- **Per-action bulk route sprawl** — the per-action decision is settled, but the route table is now large. Revisit whether a documented `?action=` discriminator on one route per resource would read better once the full set is in.
## References