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.
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-08-05
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 —
POSTto create,PATCHto update,DELETEto 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. UsesSpree.admin_user_class. - Two auth mechanisms, both already infrastructured:
- Secret API keys (
spree_sk_xxx) viaAuthorization: Bearerfor server-to-server - JWT tokens via
Authorization: Bearerfor SPA sessions
- Secret API keys (
- 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/:idis fine,/orders/:id/shipments/:id/rates/:idis 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.
- One nested products surface for every product-curating parent (2026-08-28). Categories, collections, catalogs and price lists all expose the same protocol through the
:product_membershiprouting concern +Spree::Api::V3::Admin::ProductMembershipcontroller concern:GET /{parents}/:id/products(paginated members),POST …/productswith{ product_ids: [] }→{ added_count },DELETE …/productswith{ product_ids: [] }→{ removed_count }— both writes bulk by design, counts reporting what actually changed. Per-memberPATCH …/products/:id/repositiononly where membership carries a manual order (categories, collections). A new parent that curates products joins this concern rather than inventing its own shape; membership never rides the parent's own PATCH payload (the price listproduct_idsarray did and was retired). The SDK mirrors it via oneproductMembershipbuilder (client.<parents>.products). The dashboard binds it through ONE card (DeferredProductMembershipCard, over the headlessProductMembershipListin@spree/dashboard-ui): membership is never written on click on any of the four — the picker and the rowxstage into the parent's form viaProductMembershipStagingProvider(a real RHF field, so Save/Discard,isDirtyand the unsaved-changes guards govern it), and the page's Save flushes it. Removals therefore carry no confirm — Save is the confirmation — and a staged removal restores in one click. Drag-to-reorder is the one exception and still persists on drop, disabled while anything is staged. The product-side bulk actions (POST /products/bulk_add_to_categories, …) are a different axis (N products × M parents, the products-table bulk bar) and deliberately remain.
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::AdminAuthenticationconcern added toAdmin::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/refreshlive onAdmin::AuthControllerwhich skipsauthenticate_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.pricesto include associations (max 4 levels)?q[name_cont]=shirtfor Ransack filtering?sort=-created_atfor sorting (JSON:API convention)
Example: product create/update
{
"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:
{
"error": {
"code": "validation_error",
"message": "Name can't be blank",
"details": { "name": ["can't be blank"] }
}
}
Example: order create with line items (one call)
{
"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.
{
"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 (with scopes), httpOnly refresh-cookie auth, prefixed IDs, error handling, Pagy, Ransack, CanCanCan scoping, per-action bulk-operation helper (
Spree::Api::V3::BulkOperations),custom_fieldableroute 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, StockLevel, StockMovement, StockReservation, StockTransfer, Store, AdminUser, Role, Invitation, ApiKey, AllowedOrigin, WebhookEndpoint, WebhookDelivery, Export, CustomFieldDefinition, CustomField, Tag. More are added as endpoints come online.
Endpoint rollout order
- Authentication — login, refresh, logout, me ✅
- Products + Variants + Media + Options — highest-priority, hardest, nested ✅
- Orders + Items + Fulfillments + Payments + Adjustments + Refunds ✅
- Customers + Addresses + Credit Cards + Store Credits + Customer Groups + Gift Cards ✅
- Promotions + Rules + Actions + Coupon Codes ✅
- Stock (Locations, Items, Reservations, Transfers) + Price Lists + Prices ✅ (Transfers lifecycle + Suppliers + Purchase Orders pending — see
6.0-inventory-operations.md) - Categories ✅ (read) — Collections + write/reposition pending
- Store settings ✅, Channels ✅, Markets ✅, Tax Categories ✅, Admin users ✅, Roles ✅ (read), Invitations ✅, API keys ✅, Webhooks ✅, Allowed Origins ✅, Exports ✅, Dashboard ✅, Policies ✅
- Custom Fields + Custom Field Definitions ✅ — Translations (polymorphic) pending
- Returns/Exchanges/Claims, Product Types, Collections, Marketplace (Sellers/Commission/Payouts), Delivery Methods/Zones, Tax Rates/Markets-as-tax, Payment Methods ✅ — remaining 6.0 model work; Catalogs/Companies (B2B) deferred to 6.1 per
decisions.md2026-06-16 - Reports, Imports, Integrations, Price History, Stock Movements — pending
PR process for each endpoint
- Add controller and route
- Add/extend admin serializer
- Run
bundle exec rake typelizer:generate+pnpm generate:zod - Add controller spec (+ serializer spec if new attributes)
- Add SDK resource in
@spree/admin-sdk - Mark endpoint
[x]in this plan - If public-facing: update OpenAPI spec with
bundle exec rake rswag:specs:swaggerize
Constraints on Current Work
- Never add endpoints outside
Admin::ResourceControllerhierarchy 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.updateis 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 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-6.1-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_ |
ProductPublication (replaces StoreProduct) |
— | pp_ |
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
-
POST /api/v3/admin/auth/login— admin user login (JWT + httpOnly refresh cookie) -
POST /api/v3/admin/auth/refresh— rotate refresh token (read from signed cookie), return new JWT -
POST /api/v3/admin/auth/logout— invalidate JWT and refresh token, clear cookie -
GET /api/v3/admin/me— current admin user + serialized permissions -
PATCH /api/v3/admin/me— self-service profile updates (e.g. the admin's own UI language) -
GET /api/v3/admin/auth/invitations/:id/lookup— public invitation lookup (prefixed ID + token in URL act as credential) -
POST /api/v3/admin/auth/invitations/:id/accept— public invitation acceptance (sets password, issues tokens)
5.x → 6.0: Logout shipped as
POST(notDELETE); the refresh token moved to an httpOnly signed cookie and is no longer returned in the login response body. See5.5-admin-auth-cookie-refresh.md,6.0-platform-auth.md.
Products (⭐ high priority)
-
GET /api/v3/admin/products— list (Ransack, sort, paginate) -
GET /api/v3/admin/products/:id -
POST /api/v3/admin/products— with nested variants, prices,category_ids -
PATCH /api/v3/admin/products/:id -
DELETE /api/v3/admin/products/:id— soft delete -
POST /api/v3/admin/products/:id/clone -
POST /api/v3/admin/products/bulk_status_update— bulk status change -
POST /api/v3/admin/products/bulk_add_to_categories/bulk_remove_from_categories -
POST /api/v3/admin/products/bulk_add_to_channels/bulk_remove_from_channels -
POST /api/v3/admin/products/bulk_add_tags/bulk_remove_tags -
DELETE /api/v3/admin/products/bulk_destroy
Bulk envelope decision (resolved): per-action bulk routes (not a single
/bulk), bodies{ ids: [...], ... }, shared via theSpree::Api::V3::BulkOperationsconcern. Resolves the "Bulk operations envelope" open question.
6.0 field changes:
shipping_category_idis dropped (fulfillment types come fromProductType.fulfillment_types).prototype_id→product_type_id.taxon_ids→category_ids. Product hasdefault_variant_idFK (no moreis_master).Rich-text write contract (corrected 2026-08-27, per
6.0-store-policies.md): reads aredescription(plain) +description_html(HTML); writes go to the plaindescription, whichSpree::SanitizableRichTextsanitizes on save.field_htmlis a read-only reader with no writer, which is what every shipped controller reflects (Admin::CategoriesControllerpermits:description, not:description_html). Same pattern forbody/body_htmlon Policies andinternal_note/internal_note_htmlon Orders/Customers. An earlier version of this line described*_html-on-write with a 422 on the plain param; that was never implemented and contradicted6.0-rich-text-descriptions.md's own summary.
Variants (nested under Products)
-
GET /api/v3/admin/products/:product_id/variants -
GET /api/v3/admin/products/:product_id/variants/:id -
POST /api/v3/admin/products/:product_id/variants— with nested prices -
PATCH /api/v3/admin/products/:product_id/variants/:id -
DELETE /api/v3/admin/products/:product_id/variants/:id
Variants (top-level — search / autocomplete across all products)
-
GET /api/v3/admin/variants— flat variant search (e.g. order line-item picker); supportscustom_fields -
GET /api/v3/admin/variants/:id
Prices
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.)
-
GET /api/v3/admin/prices— list (filter by variant, currency, price_list) -
GET /api/v3/admin/prices/:id -
POST /api/v3/admin/prices -
PATCH /api/v3/admin/prices/:id -
DELETE /api/v3/admin/prices/:id— soft delete -
POST /api/v3/admin/prices/bulk_upsert— upsert on(variant_id, currency, price_list_id) -
DELETE /api/v3/admin/prices/bulk_destroy
Product Media (nested under Products, replaces Assets)
-
GET /api/v3/admin/products/:product_id/media— list (filterable bymedia_type) -
POST /api/v3/admin/products/:product_id/media— upload via multipart ORsource_urlparam (async download). Params:media_type,alt,position,variant_ids -
PATCH /api/v3/admin/products/:product_id/media/:id— update alt, position, variant assignment (variant_ids: []) -
DELETE /api/v3/admin/products/:product_id/media/:id -
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 thevariant_idsarray (Spree::VariantMediajoin).expand=images→expand=media. See5.4-6.0-product-media-system.md.
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
-
GET /api/v3/admin/option_types -
GET /api/v3/admin/option_types/:id -
POST /api/v3/admin/option_types -
PATCH /api/v3/admin/option_types/:id -
DELETE /api/v3/admin/option_types/: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 -
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_typesJSON array column (['shipping']default). Product types can require specificCustomFieldDefinitions via nested definition records. See6.0-product-types.md.
Categories (renamed from Taxons; Taxonomy dropped)
-
GET /api/v3/admin/categories— list with tree metadata -
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::Categorybelongs directly toSpree::Store(no Taxonomy).Classification→ProductCategory. See6.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 nestedrules(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.CollectionRulereplacesTaxonRule. See6.0-replace-taxons-with-categories.md.
Channels (new in 6.0) — shipped 5.5
-
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 -
POST /api/v3/admin/channels/:id/add_products— bulk publish (product_ids, optionalpublished_at/unpublished_at) -
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.).
Channel#defaultresolves the store's default channel. See6.0-channels-catalogs-b2b.md,6.0-order-routing.md.
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 -
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)
-
GET /api/v3/admin/orders -
GET /api/v3/admin/orders/:id -
POST /api/v3/admin/orders— create draft -
PATCH /api/v3/admin/orders/:id -
DELETE /api/v3/admin/orders/:id -
PATCH /api/v3/admin/orders/:id/complete -
PATCH /api/v3/admin/orders/:id/cancel -
PATCH /api/v3/admin/orders/:id/approve -
PATCH /api/v3/admin/orders/:id/resume -
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 /nextand/advanceno longer apply and have been removed from the 5.x admin API ahead of the 6.0 cart/order split. Cart and Order are separate models;LineItemowner is the dual-FK pattern (cart_id/order_idexactly-one,#ownermethod — 2026-07-27). Order gainschannel_id,company_location_id,withdrawal_eligible_untilFKs.
Items (nested under Orders — matches Store API /carts/:id/items convention)
-
GET /api/v3/admin/orders/:order_id/items -
GET /api/v3/admin/orders/:order_id/items/:id -
POST /api/v3/admin/orders/:order_id/items -
PATCH /api/v3/admin/orders/:order_id/items/:id -
DELETE /api/v3/admin/orders/:order_id/items/:id
Fulfillments (nested under Orders; replaces Shipments)
-
GET /api/v3/admin/orders/:order_id/fulfillments -
GET /api/v3/admin/orders/:order_id/fulfillments/:id -
POST /api/v3/admin/orders/:order_id/fulfillments— manual fulfillment creation (external carrier / 3PL sync): moves not-yet-shipped units out of routed fulfillments, bypassing order routing; optionalitems,delivery_method_id,tracking,status: 'shipped' -
PATCH /api/v3/admin/orders/:order_id/fulfillments/:id -
PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/fulfill— mark as fulfilled -
PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/cancel -
PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/resume -
PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/split
6.0: Third-party fulfillment via
FulfillmentProviderinterface.pickup_point_dataJSON snapshot for pickup points. See6.0-fulfillment-and-delivery.md.
Payments (nested under Orders)
-
GET /api/v3/admin/orders/:order_id/payments -
GET /api/v3/admin/orders/:order_id/payments/:id -
POST /api/v3/admin/orders/:order_id/payments— supports off-session admin charges viasource_id(savedSpree::CreditCardbelonging to the order's customer) -
PATCH /api/v3/admin/orders/:order_id/payments/:id/capture -
PATCH /api/v3/admin/orders/:order_id/payments/:id/void
Off-session charges: pass
{ payment_method_id, source_id, amount }to charge a saved card. There is no separate "PaymentSession" endpoint on the admin side — the cart/store API haspayment_sessionsfor SCA/3DS storefront flows; admin-initiated charges use saved sources directly.
Refunds (nested under Orders)
-
GET /api/v3/admin/orders/:order_id/refunds -
POST /api/v3/admin/orders/:order_id/refunds— withpayment_idin body -
PATCH /api/v3/admin/orders/:order_id/refunds/:id
Adjustments (nested under Orders, read-only in 5.x; replaced by typed endpoints in 6.0)
-
GET /api/v3/admin/orders/:order_id/adjustments -
GET /api/v3/admin/orders/:order_id/adjustments/:id
5.x → 6.0: The 5.x admin API exposes
/adjustmentsas read-only (no create/update/destroy) so client integrations don't depend on a write surface that is going away. Manual adjustment management has been removed. In 6.0, this endpoint is replaced by the three typed endpoints below.
Tax Lines (nested under Orders, read-only; replaces Adjustments in 6.0)
-
GET /api/v3/admin/orders/:order_id/tax_lines
Discounts (nested under Orders, read-only; replaces Adjustments in 6.0)
-
GET /api/v3/admin/orders/:order_id/discounts
Fees (nested under Orders, read-only; replaces Adjustments in 6.0)
-
GET /api/v3/admin/orders/:order_id/fees
6.0: Polymorphic
Spree::Adjustmentis dropped. Tax, discount, and fee data is returned via typed, read-only endpoints. See6.0-6.1-split-adjustments.md.
Order Customer Assignment
Customer assignment is handled via the standard PATCH /api/v3/admin/orders/:id endpoint with customer_id in the body. No dedicated endpoint. Pass customer_id: null to unassign.
-
PATCH /api/v3/admin/orders/:id { customer_id }— assign / reassign / unassign customer (5.x bridge: also acceptsuser_id)
Order Gift Cards (nested under Orders)
-
POST /api/v3/admin/orders/:order_id/gift_cards { code }— apply a gift card by code -
DELETE /api/v3/admin/orders/:order_id/gift_cards/:id— remove the applied gift card
Order Store Credits (nested under Orders)
-
POST /api/v3/admin/orders/:order_id/store_credits { amount? }— apply customer's available store credit (auto up to balance, or a specificamount) -
DELETE /api/v3/admin/orders/:order_id/store_credits— remove store credit application
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 → Reimbursementchain. See6.0-returns-exchanges-claims.md.
Customers (users) — shipped 5.5
-
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/bulk_add_to_groups/bulk_remove_from_groups -
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 nestedmembersendpoints.
Customer Addresses (nested under Customers) — shipped 5.5
-
GET /api/v3/admin/customers/:customer_id/addresses -
GET /api/v3/admin/customers/:customer_id/addresses/:id -
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
Default-address handling via
is_default_billing/is_default_shippingflags 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
-
GET /api/v3/admin/customers/:customer_id/credit_cards -
GET /api/v3/admin/customers/:customer_id/credit_cards/:id -
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
-
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 -
GET /api/v3/admin/gift_card_batches -
GET /api/v3/admin/gift_card_batches/:id -
POST /api/v3/admin/gift_card_batches— batch create
Customer Groups — shipped 5.5
-
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 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 -
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/promotion_actions -
GET /api/v3/admin/promotions/:promotion_id/promotion_actions/:id -
POST /api/v3/admin/promotions/:promotion_id/promotion_actions -
PATCH /api/v3/admin/promotions/:promotion_id/promotion_actions/:id -
DELETE /api/v3/admin/promotions/:promotion_id/promotion_actions/:id -
GET /api/v3/admin/promotion_actions/types— registered action subclasses + preference schemas (for the "Add action" picker) -
GET /api/v3/admin/promotion_actions/calculators— registered calculator subclasses + preference schemas forCalculatedAdjustmentsactions
Promotion Rules (nested under Promotions)
-
GET /api/v3/admin/promotions/:promotion_id/promotion_rules -
GET /api/v3/admin/promotions/:promotion_id/promotion_rules/:id -
POST /api/v3/admin/promotions/:promotion_id/promotion_rules -
PATCH /api/v3/admin/promotions/:promotion_id/promotion_rules/:id -
DELETE /api/v3/admin/promotions/:promotion_id/promotion_rules/:id -
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 -
GET /api/v3/admin/promotions/:promotion_id/coupon_codes/:id
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 Levels
-
GET /api/v3/admin/stock_levels— filterable by stock_location, variant -
GET /api/v3/admin/stock_levels/:id -
PATCH /api/v3/admin/stock_levels/:id— a count edit is written as anadjustedmovement, and takes an optionalreason -
DELETE /api/v3/admin/stock_levels/:id
6.0: renamed from
stock_items, prefixsi_→sl_. No route alias is kept. See6.0-typed-stock-movements.md.
Stock Movements (read-only; typed in 6.0)
-
GET /api/v3/admin/stock_movements— filterable bykind,stock_level_id,fulfillment_id,order_id,return_id,exchange_id,stock_transfer_id -
GET /api/v3/admin/stock_movements/:id
6.0:
StockMovementcarries akind(received,allocated,shipped,released,adjusted) + concrete FKs to the originating event. Read-only by route — there is no create, update or destroy. See6.0-typed-stock-movements.md.
Stock Reservations (read-only; new in 6.0)
-
GET /api/v3/admin/stock_reservations— filterable by variant, order, cart -
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— 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.
Suppliers (new in 6.0)
-
GET /api/v3/admin/suppliers -
GET /api/v3/admin/suppliers/:id -
POST /api/v3/admin/suppliers -
PATCH /api/v3/admin/suppliers/:id -
DELETE /api/v3/admin/suppliers/:id
6.0:
Spree::Supplieris the procurement source for purchase orders (see6.0-inventory-operations.md). Not to be confused with marketplace Sellers below —Spree::Selleris the marketplace seller (6.0-multi-vendor-marketplace.md,decisions.md2026-07-14).
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::Supplierreplace today's "external receive" hack. See6.0-inventory-operations.md.
Marketplace (new in 6.0)
Per 6.0-multi-vendor-marketplace.md. Seller prefix is sel_ (matches the legacy Enterprise gem).
-
GET /api/v3/admin/sellers -
GET /api/v3/admin/sellers/:id -
POST /api/v3/admin/sellers -
PATCH /api/v3/admin/sellers/:id -
DELETE /api/v3/admin/sellers/:id -
POST /api/v3/admin/sellers/:id/invite— (re)send the seller invitation (Spree::Invitation,resource: seller) -
POST /api/v3/admin/sellers/:id/approve/POST /api/v3/admin/sellers/:id/reject/POST /api/v3/admin/sellers/:id/suspend— lifecycle transitions (approve also un-suspends) -
GET /api/v3/admin/commission_rates -
GET /api/v3/admin/commission_rates/:id -
POST /api/v3/admin/commission_rates -
PATCH /api/v3/admin/commission_rates/:id— saves rate fields + nestedrules: []in one round-trip (PriceList-style) -
DELETE /api/v3/admin/commission_rates/:id -
GET /api/v3/admin/commission_lines— read-only snapshot ledger (filter by seller/order) -
GET /api/v3/admin/seller_transfers— read-only earnings ledger (filter by seller/payout/status;read_payouts) -
GET /api/v3/admin/seller_payouts/GET /:id -
PATCH /api/v3/admin/seller_payouts/:id/complete— manual settlement (system provider;write_payouts) -
GET /api/v3/admin/sellers/:id/balances— earned / paid / owed / in-flight, one row per currency (read_payouts) -
POST /api/v3/admin/sellers/:id/payouts— settle a seller by hand, one payout per currency owed; what themanualinterval means (write_payouts) -
GET /api/v3/admin/order_groups/GET /:id— the multi-order transaction container (read-only;read_orders)
API key scopes: read_sellers / write_sellers, read_commissions / write_commissions, read_payouts / write_payouts.
Operator surface only (2026-08-15). Seller users never call the Admin API. They are
Spree::AdminUseraccounts signing in through a dedicated/api/v3/sellerbranch with its ownseller_apiJWT audience and login registry, where every endpoint scope-fetches throughcurrent_seller; the seller endpoint list and serializer rules live in6.0-multi-vendor-marketplace.md→ "Seller API surface" (Decision 10,decisions.md2026-08-15).
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— saves name/schedule/match policy +product_ids: []+ nestedrules: []+prices: []in one round-trip -
DELETE /api/v3/admin/price_lists/:id -
PATCH /api/v3/admin/price_lists/:id/activate— draft|inactive → active (or scheduled whenstarts_atis in the future) -
PATCH /api/v3/admin/price_lists/:id/deactivate -
GET /api/v3/admin/price_lists/:id/prices— spreadsheet data feed (filter by?currency=) -
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"
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 -
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 -
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(registered set — 6.0 built-ins:shipping,pickup,digital;pickup_pointdeferred to 6.1,local_deliverycut — decisions.md 2026-08-06). See6.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
-
GET /api/v3/admin/tax_categories -
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: a rate names its jurisdiction directly as
country_code+state_codecodes, and tax logic moves behind aTaxProviderinterface. See6.0-tax-provider.md.
spree_tax_rates.zone_idis not dropped in 6.0:spree:migrate_tax_zonesreads it to convert existing rates, and that task runs afterdb:migrate, so removing the column in the same release would destroy its own input. It stays unread through 6.0 and comes off in 6.1.Built by the tax-provider plan (2026-08-05), Phase 3. These rows are the Internal provider's entire configuration, so that plan cannot verify its own tax calculation without them, and it specifies the serializer alongside the provider work. They shipped against the
zone_idshape and moved to the jurisdiction codes in its Phase 5.
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— supports?expand=statesfor state/province dropdowns -
GET /api/v3/admin/countries/:id
Store Settings
-
GET /api/v3/admin/store -
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 -
PATCH /api/v3/admin/admin_users/:id -
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). See6.0-platform-auth.md.
Roles
-
GET /api/v3/admin/roles— feeds role pickers + the roles settings page -
GET /api/v3/admin/roles/:id -
POST /api/v3/admin/roles -
PATCH /api/v3/admin/roles/:id -
DELETE /api/v3/admin/roles/:id -
GET /api/v3/admin/permissions— the permission catalog (grant vocabulary discovery)
Shipped with
6.0-admin-rbac.md: DB-backed role permissions (catalog keys),/me.permission_keys, and thesettings→staffscope split for this whole staff group.
Invitations
-
GET /api/v3/admin/invitations -
GET /api/v3/admin/invitations/:id -
POST /api/v3/admin/invitations -
DELETE /api/v3/admin/invitations/:id -
PATCH /api/v3/admin/invitations/:id/resend
Public acceptance endpoints (
GET/POST /auth/invitations/:id/...) live under Authentication above.
Allowed Origins (CORS allowlist)
-
GET /api/v3/admin/allowed_origins -
GET /api/v3/admin/allowed_origins/:id -
POST /api/v3/admin/allowed_origins -
PATCH /api/v3/admin/allowed_origins/:id -
DELETE /api/v3/admin/allowed_origins/:id
Direct Uploads (Active Storage)
-
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
6.0:
display_on→storefront_visible(boolean).metafield_type→field_type. See5.4-6.0-custom-fields-rename.md.
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.
-
GET|POST /api/v3/admin/products/:product_id/custom_fields+PATCH|DELETE .../custom_fields/:id -
…/variants/:variant_id/custom_fields -
…/categories/:category_id/custom_fields -
…/option_types/:option_type_id/custom_fields -
…/customers/:customer_id/custom_fields -
…/orders/:order_id/custom_fields
New parents get custom-field endpoints for free by adding
concerns: :custom_fieldableto their route + includingSpree::Metafieldson 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— 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, thetags: []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 -
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
Removed 2026-08-18 — store credits no longer carry a category (see decisions.md); the read-only endpoints were deleted with the model's use.
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 -
POST /api/v3/admin/webhook_endpoints/:id/send_test— fire a test delivery -
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 -
POST /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id/redeliver
API Keys
-
GET /api/v3/admin/api_keys -
GET /api/v3/admin/api_keys/:id -
GET /api/v3/admin/api_keys/current— the key the request authenticated with -
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
Keys carry Shopify-style
read_*/write_*scopes. See5.5-admin-api-key-scopes.md.
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— includesdone,download_url,filename,byte_size -
POST /api/v3/admin/exports— typeSpree::Exports::{Products,Orders,Customers}+ optionalsearch_params/record_selection -
DELETE /api/v3/admin/exports/:id -
GET /api/v3/admin/exports/:id/download— redirect to the generated file
No
PATCH— exports are immutable once created. See5.5-admin-spa-csv-export.md.
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
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 theSpree::Api::V3::BulkOperationsconcern. No single/bulkenvelope. - Order customer assignment — ✅ resolved:
PATCH /orders/:id { customer_id }(5.x bridge also acceptsuser_id). No dedicated sub-resource. - Polymorphic custom fields routing — ✅ resolved:
custom_fieldsmounted via thecustom_fieldableroute concern under each parent resource, not a flat/:resource_type/:resource_id/custom_fieldsroute.
Open Questions
- 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
docs/api-reference/store-api/errors.mdx— error response conventions (shared)docs/plans/6.0-admin-spa.md— consumer of this APIdocs/plans/6.0-platform-auth.md— auth stack andSpree.admin_user_classrenamedocs/plans/5.4-6.0-custom-fields-rename.md— Metafields → Custom Fieldsdocs/plans/6.0-fulfillment-and-delivery.md— shipping category dropped