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.
@spree/admin-sdk
6.0.2
Patch Changes
#15057
ab0dec3Thanks @damianlegawiec! - Admin API payments now returncan_voidandcan_capture, which the payment method decides. The order page uses them to hide Void on captured payments that the gateway cannot void, such as Stripe. The dashboard no longer checks the payment status itself, so it needs a server that returns them.#15040
7416961Thanks @damianlegawiec! - The staff settings page shows each member's status (active, locked or deactivated) and when they were last active. A new "View details" action opens a sheet with when they joined, who invited them and their signed-in sessions, each with its browser, IP address and last use. The admin SDK types gainstatus,last_active_at, theinviterandsessionsexpands, and theSessionandAdminUserStatustypes;@spree/dashboard-uiaddsBrowserIcon.
6.0.1
Patch Changes
#15006
f227994Thanks @damianlegawiec! - The admin dashboard now shows external references (the keys an ERP, PIM or CRM knows a record by) in the Metadata card, each with a copy button. They appear on product, order, category, company and seller pages, in the metadata sheet of returns and fulfillments, and in the stock location edit panel. The Admin API now returns external references for sellers too.#14996
30493b4Thanks @damianlegawiec! - Added an optionalcustom_fieldsproperty to every record type that can carry custom fields, such as sellers, option types, media, orders, line items, addresses and customers. Request it withexpand: ['custom_fields']. The Store API returns only fields marked storefront visible, and the Admin API returns every field.#15001
21dc28fThanks @damianlegawiec! - Typed the store's regional settings. The store'sdefault_country_codeis nowCountryCode, itsadmin_localeisLocaleCode(sendnullto clear it), and itstimezone— also on the seller profile — is the newTimeZonetype, which suggests common IANA time zones while accepting any other.TIME_ZONESin@spree/corelists the suggested zones.#14997
730c9daThanks @damianlegawiec! - Added localized storefront SEO settings. Merchants edit the store's SEO title and meta description on Store Settings and translate them for each supported language. The Store SDK reads them withclient.store.get(), and the Admin SDK reaches the store's translations withclient.store.translations.get().
6.0.0
Minor Changes
- #14982
348c5bbThanks @damianlegawiec! - Added maintenance task runs and upgrade steps.upgradeSteps.list()returns the data steps a Spree upgrade still needs, in the order they must run, each with its last run.maintenanceTaskRunslists, gets and starts runs, andmaintenanceTaskRuns.cancel()stops one. Runs belong to the whole installation, and a task is named by its short name (capture_methods), never a Ruby class name.
6.0.0-rc.7
Released with Spree 6.0.0.rc7, with no changes of its own. From this release the version matches the version of the Spree gems.
1.0.0-rc.6
Minor Changes
#14971
98a79caThanks @damianlegawiec! - Sellers can manage the downloadable files on their own digital products. The Seller SDK addsproducts.digitalAssets(list,get,create,update,delete), and the seller panel's product page shows the same Digital files card as the dashboard: upload, replace and delete files, and set per-file download limits. A file the marketplace delivers through its own provider is listed but cannot be replaced by the seller. The card now lives in@spree/dashboard-coreasDigitalAssetsCard, and a panel enables it by registeringdigitalAssetson its API client;readOnlyshows the files without any way to change them andacceptnarrows the file picker.Seller uploads are a marketplace decision: three store settings, edited on the dashboard's Marketplace settings page, say whether sellers may upload at all (off by default), which content types their files may have, and whether a file added to or replaced on an approved product sends it back to review. The seller
/meresponse carries them understore, and the Admin SDK'sStoretype gains the three fields.
Patch Changes
#14952
caaaee2Thanks @damianlegawiec! - A store credit'screated_byis now anActorrather than anAdminUser, since a credit issued with a secret API key records the key as its issuer. The dashboard hides refunding a return, resolving a claim, fulfilling an exchange and refunding on cancel from roles without the refunds permission.#14970
fb8a9ceThanks @damianlegawiec! - A webhook endpoint's subscriptions must now be*, an event name, or a name with*in place of whole segments (order.*,*.created), with at most 200 entries of up to 100 characters each; the API's 422 names the rejected entries.@spree/coreexports the rule asWEBHOOK_EVENT_PATTERN,isWebhookEventPattern,WEBHOOK_SUBSCRIPTION_MAX_LENGTHandWEBHOOK_SUBSCRIPTIONS_MAX, and the dashboard's webhook form checks it before saving, refusing an invalid custom event inline.FieldErrorno longer crashes on the sparse per-item error array react-hook-form produces.
1.0.0-rc.5
Minor Changes
#14911
3ca1f5eThanks @KacperMekarski! - Company members can now pick their company's addresses when choosing where an order goes. Picking a company site at checkout used to be dropped without an error, because the cart only ever looked in the buyer's own address book. A newGET /store/carts/:id/addressesreturns everything a cart may be shipped or billed to — the buyer's book plus the sites of the company set as the cart'scompany_idand the ones it inherits, limited to the countries the cart's market sells to — andclient.carts.addresses.list()reaches it. The company has to be set on the cart explicitly: a buyer who belongs to a single company is not assumed to be buying for it when it comes to addresses. EveryAddressnow carries theownerit is filed under (nullfor an address in no book, such as the copy a placed order keeps), so a picker can label the two books from one response. On the Admin API thisownerobject replaces the separateowner_idandowner_typefields. Unlike the other cart endpoints this one needs a signed-in customer: it answers with the account's address books rather than the cart's own contents. Staff get the same reach: a company's sites are selectable when creating an order, and "use default addresses" takes the company's defaults for a company order. On a division's page, addresses inherited from the companies above it are labelled with their owner and cannot be edited there.#14939
9c73a79Thanks @damianlegawiec! - Added custom field editing to variants, option types, sellers, promotions, gift cards, store credits, stock transfers, purchase orders, companies, payment methods, delivery methods, tax rates, product types, media and store settings. Sheets show the custom fields card only once the store defines a field for that type. On the product page, variant and media custom fields save with the sheet's Done, and widgets in theirproduct.variant.form_fieldsandproduct.media.form_fieldsslots can save on Done throughonSave.FormActionsanduseFormSubmitShortcutacceptdirtyfor unsaved changes held outside the form.client.customFields(ownerType, ownerId)accepts each of these types.#14937
90f8f59Thanks @damianlegawiec! - New draft orders take a market, sales channel, currency and locale, chosen before any item is added. A market fixes the currency and the locales on offer. The item search on a new or existing draft order lists only what the buyer can be sold on that channel, priced as they would pay in that market;variants.list()acceptsorder_id, ormarket_id,channel_id,customer_id,company_idandcurrencyfor an order not yet created.order_idcannot be combined with the other fields, andcurrencyon its own also narrows the list. Order creation refuses items the buyer cannot order on the channel, and picks a market selling the requested currency when none is named. Changing any of these after items are picked asks before removing them.
Patch Changes
#14933
1a86817Thanks @damianlegawiec! - Order filter and sort types includemarket_idandlocale. Locale, currency and country filters (locale,currency,cost_currency,country_code,country_of_origin) accept onlyLocaleCode,CurrencyCodeandCountryCodevalues (newCodeFilterstype) instead of free text.#14934
dc2f1a7Thanks @mad-eel! - A customer's own data request now waits for confirmation from the account's email address.client.customer.dataRequestslists, reads and opens requests, andcreatetakes aredirect_urlfor the page the emailed link opens.client.dataRequests.confirm(token)confirms one from that page, andclient.dataRequests.get(token)reads it, with the download link once the export is ready.DataRequestStatusgainsawaiting_confirmationandlapsed. The dashboard's email editor lists the new confirmation email.#14944
a0e5b66Thanks @damianlegawiec! - Added every status, kind and other value list the Spree API returns to@spree/core, each as a list of its values (PRODUCT_STATUSES,MEDIA_TYPES, …) and a type (ProductStatus,MediaType, …) — open where extensions may add values, closed otherwise — plussubsetOffor picking the values an action accepts with each one checked at compile time. The SDKs re-export these types instead of each carrying its own copy, so their names and values are unchanged. The dashboards and the seller panel build their status filters and action checks from these lists, so a status added on the server shows up without a dashboard change. Value lists the SDKs used to spell out inline, such as a seller transfer'skind, now have names of their own;MediaType,CollectionRuleMatchPolicyandCollectionSortOrderin@spree/admin-sdk, andClaimResolutionin@spree/dashboard-ui, now come from the generated lists under the same names. A seller'stax_remittanceandpayouts_schedule_interval, a claim'sresolution, a collection'ssort_order, a shipping label'sformat, purchase order and stock transfer statuses, and tax and commission lines'taxability_reasonare now typed with their lists instead of as plain strings.#14936
06fc8b0Thanks @damianlegawiec! - Weight and dimension units are closed code lists, exported asWeightUnitandDimensionUnit(values and types) likeCountryCodeandCurrencyCode, and every unit field in responses and request types uses them; unit fields in requests acceptnullto fall back to the store default. The Admin and Seller SDKs publish oneVariantParamstype:ProductVariantParams,VariantCreateParamsandVariantUpdateParamsbuild on it. The Seller SDK'sSellerProductVariantParamsis renamed toProductVariantParams(the old name stays as a deprecated alias). The variant editor and bulk variant editor now offer feet as a dimension unit.
1.0.0-rc.4
Minor Changes
#14912
67c98acThanks @damianlegawiec! - AddedstockReservations.list,consentRecords.list,dataRequests.list,dataRequests.createandsellers.customFields, so every Admin API endpoint can be called through the SDK. Every endpoint in the Admin API reference now also shows an SDK example.#14833
b38df6eThanks @mad-eel! - Tax rates no longer haveincluded_in_price, in responses, create and update params, filters or sort. Whether prices include tax is now the market'stax_inclusivesetting.#14900
11b9a03Thanks @damianlegawiec! - AddedCountryCode,CurrencyCodeandLocaleCodeas values as well as types, so you can writeCurrencyCode.USD, list every code withObject.values(CurrencyCode)and see each code's name in your editor. Plain strings such as'USD'still type-check.#14916
a7aa0e5Thanks @damianlegawiec! - Admin API payments now includeavs_riskyandcvv_risky, and can expandcapture_events, each capture of the money the payment authorized. On the order page, a payment whose card failed the issuer's checks is flagged, and each payment's menu opens a details dialog with the address and security code check results and the list of captures.#14913
9688d11Thanks @damianlegawiec! - Admin API payments now includegateway_dashboard_payment_url, a link to the payment in the payment provider's own dashboard. On the order page, each payment's menu shows a "View at {payment method}" link when the provider offers one, so staff can look up the full payment details there.#14922
214c5aaThanks @damianlegawiec! - AddedtaxExemptionReasons, the store's own list of reasons a business can give for buying without tax, with list, get, create, update and delete. Each reason has acodethe tax engine receives. Tax exemption certificates now point at a reason withtax_exemption_reason_idinstead of recordingreason_code, and can expandtax_exemption_reason.taxProviders.list()is now typed (TaxProviderOption) and says which exemption reason codes each engine reads. The dashboard gains one Settings → Taxes page with tabs for tax categories, tax rates and exemption reasons, which also shows the tax service each market uses; the certificate form offers the store's reasons.
Patch Changes
#14905
e7d276dThanks @damianlegawiec! - The email branding preview now shows a newly uploaded or removed logo before saving, and refreshes after saving. The logo now sits in the Branding section of email settings.EmailTemplatePreviewParamsacceptsmailer_logo_signed_id.#14914
1ff3b91Thanks @damianlegawiec! -unit_costis now required on every purchase order item (PurchaseOrderItemParams), matching what the API already enforced. The dashboard's purchase order form now starts each line with an empty cost, so Save stays disabled until the merchant prices every line, instead of filling in zero.
1.0.0-rc.3
Patch Changes
Entries of
qon every list method always stay insideq, even one namedpageorsort, and nested objects are sent in bracket form.sumMoney,subtractMoney,multiplyMoneyandnegateMoneynow write every result the same way: with the decimals their inputs carry, and at least the currency's when one is given (sumMoney(['1.50', '2.50'])is"4.00", not"4"). Nothing is rounded away.formatMoneyreturns an empty string for a currencyIntldoes not know, falls back to the reader's language for a locale it does not know, and no longer shows a minus sign on an amount that rounds to zero.
1.0.0-rc.2
Minor Changes
#14856
05d6372Thanks @damianlegawiec! - The Admin and Seller APIs no longer returndisplay_*money fields, so their types drop them; format the amount with its currency instead. The dashboard and seller panel format every amount in the admin's own language.formatMoneywrites a currency's ISO 4217 decimals and takes{ unitPrice: true }for up to four.#14866
cbde8feThanks @damianlegawiec! -directUploads.create()is replaced byfiles.create()andfiles.upload(), which uploads a file and resolves to asigned_idin one call, either straight to storage or in the request itself. Thesigned_idexpires after a day. Every parameter that takes one is now namedsigned_idor<slot>_signed_id(avatar_signed_id,logo_signed_id,attachment_signed_id,document_signed_id,file_signed_id,po_document_signed_id, …). In@spree/dashboard-core,useDirectUploadbecomesuseFileUpload({ visibility }), andsignedIdParambuilds the three-state write for an image or document field.#14885
34b80f0Thanks @damianlegawiec! - AddedformatMoney(amount, currency, locale?, { unitPrice? }), which formats a decimal-string amount in its currency and the reader's language with the currency's own decimal places, without passing it through a JavaScript number. The dashboard now uses the SDK's copy.#14887
9b5911dThanks @damianlegawiec! - Country and currency names move to the client: the Store API's countrynameand currencynameandsymbolare deprecated (name them withIntl.DisplayNames, format amounts withformatMoney), and the Admin and Seller APIs no longer return a country'sname. The seller SDK'sSellerCountryis now the generatedCountrytype, and the setup country list'slocalesare typed asLocaleCode[]. The dashboard and seller panel name and sort countries in the admin's own language.In
@spree/dashboard-core,CountryOptionno longer hasnameandcountryFilteris removed: name countries withuseCountryDisplayNameand sort them with the newuseSortByCountryName, which collates in the admin's language.#14886
6034c11Thanks @damianlegawiec! - Added theLocaleCodetype: the locale codes Spree accepts (every ISO 639-1 language plus regional variants such asen-USandpt-BR). Order, cart and market locales, the store's default, supported and available locales, and the matching request params now use it. The dashboard validates locale fields with the newlocaleCodeSchema.The Store API's locale
nameis deprecated (name a locale from itscodewithIntl.DisplayNames) and the Admin API no longer returns it, so the admin SDK'sLocaletype dropsnameand typescodeasLocaleCode; the dashboard names locales in the browser.#14852
525959dThanks @damianlegawiec! - Money is a decimal string written to its currency's decimals, and Admin and Seller writes take money and rates only as decimal strings. AddedsumMoney,subtractMoney,multiplyMoney,negateMoney,compareMoney,isZeroMoney,isDecimalStringanddecimalPlacesfor exact arithmetic on those strings. Currencies carrydecimal_places; prices no longer carryamount_in_centsorcompare_at_amount_in_cents; tax rates read and writerateandrate_percentinstead ofamountandamount_percentage.#14877
8dbe607Thanks @KacperMekarski! -orders.getnow returnsOrder | OrderGroup. Called with the id of the cart a checkout was placed from, it returns the whole purchase: one order, or, when the checkout reached several sellers, the order group holding one order per seller. Narrow the result withisOrderGroupbefore reading order-only fields such asitems. An order group now carries the same money summary as an order (delivery, discount, tax, fee, gift card and store credit totals, the amount still due) and its payments.store_credit_totalon carts, orders and order groups no longer includes what a gift card paid. That amount is reported only ingift_card_total, so a summary that shows both rows no longer deducts it twice.amount_dueno longer subtracts store credit that has already been captured.#14879
f184f25Thanks @damianlegawiec! - Methods that delete a record are nameddeletein both SDKs. In the Seller SDK,taxIdentifiers.remove,team.removeandinvitations.revokeare nowtaxIdentifiers.delete,team.deleteandinvitations.delete. In the Admin SDK,sellers.team.removeandsellers.invitations.removeare nowsellers.team.deleteandsellers.invitations.delete. Methods that detach something from a cart or order (remove), or change a record without deleting it (revoke), keep their names.Seller SDK types are corrected:
team.invitereturns theInvitation, andauth.providersreturnsAuthProvidersResponse.#14858
a90a9ccThanks @damianlegawiec! - Every filterable list method now takes typed filter and sort parameters, including returns, claims, exchanges, custom fields, digital links, payouts, imports and the rest that still accepted any key. The building block for custom field value filters is nowCustomFieldValueFilters, so it no longer hides the generated filters for custom field lists. The product digital files list now pages by 25 as intended.#14854
90af080Thanks @damianlegawiec! - List methods of documented endpoints now accept typed filter and sort parameters, generated from the filters each endpoint actually accepts; methods of endpoints the API reference does not document yet keep loose parameters. A misspelled filter, a filter the endpoint does not support, or an unknown sort field is now a type error instead of a request that silently returns the unfiltered list.ProductListParams,CategoryListParams,CollectionListParamsandOrderListParamskeep their names and are now generated; they no longer accept arbitrary keys. Filters an app adds through its own extensions can be sent unchecked insideq(list({ q: { erp_id_eq: 'ERP-1' } })), generated as declarations withspree filters types, or declared by hand by extending<Resource>FilterExtensionsand<Resource>SortExtensions. The filter building blocks (TextFilters,SortKey, …) are exported for those declarations.The dashboard's allowed-origins search, delivery zones by profile, and several filters and sorts on payment methods, sellers, option types, markets, custom field definitions and gift cards now take effect; the API used to ignore them.
#14876
5c1eeeeThanks @damianlegawiec! - Request types that served both create and update are split by action, so creating marks what the API requires (a company's or tax rate's name, a tax registration's kind and value, an address's name, street, city and country) while updating takes any field.AddressParamsandCompanyAddressParamsin@spree/sdkstay as deprecated aliases until 6.1. The Admin SDK'sorders.payments.capture(orderId, id, params?, options?)takes an optional{ amount }for a partial capture; request options move from the third argument to the fourth.A tax exemption certificate's
issued_at,expires_atandverified_atare typedstring | null: a certificate that is still pending has no dates yet.#14853
3001ebfThanks @damianlegawiec! - Changed preferences to a typed contract. Every/…/typesentry returnsschema, the JSON Schema of the type'spreferences, instead ofpreference_schema, and rows no longer repeat it;PreferenceFieldandDeliveryPreferenceFieldare replaced byPreferenceSchema. Each configurable family's settings are typed pertype(PromotionRulePreferencesMap,TypedPromotionRule, …), and an extension adds its own by declaration merging. Store, channel, import and seller profile settings drop thepreferred_prefix (guest_checkout,timezone,delimiter), the store's decimal settings are strings, and delivery methods read and writecalculator: { type, preferences }. Preference writes are validated, refused withinvalid_preferencesand a JSON pointer per failing value.paymentMethods.types()lists every provider withinstalledset on those the store already has.#14871
6990f37Thanks @damianlegawiec! - Request body types are now generated from the API itself, so every create, update and action method takes exactly the fields its endpoint accepts. Fields the API never accepted are gone from the types, and fields it accepted but the types left out are added. Renamed types keep their old names as deprecated aliases (for exampleVariantPriceis nowPriceParams,LineItemInputis nowLineItemInputParams). The dashboard now saves the store's digital download limits, which the API used to drop.Country and currency codes are typed as the closed
CountryCodeandCurrencyCodeunions in both requests and responses. Deprecated fields are marked@deprecatedin the types; the Store SDK keeps them until 6.1, while the Admin and Seller SDKs drop them (addresscountry_iso/state_abbr, cartnumber, marketcountry_isos, importowner_type/owner_id, payment methodauto_capture).
Patch Changes
#14874
293200eThanks @damianlegawiec! -orders.discounts.create()takes the discount asvalue(withvalue_type); the olderamountspelling on create is gone.orders.discounts.update()still editsamount.#14864
614347aThanks @damianlegawiec! - The email template editor inserts an amount through themoneyfilter ({{ order.total | money }}) instead of a pre-formatteddisplay_*field. Email types gain the raw amounts the default templates now format:total_minus_store_credits, a line item's and a parcel item'samount, a parcel item'sprice, a fulfillment group'scostandunpriced, and a return'srefunded_total.#14884
9736316Thanks @damianlegawiec! - Removed thedisplay_*money fields from theEmail*types and Zod schemas; templates format amounts with themoneyfilter. AddedEmailCustomer,EmailCustomerGroupandEmailNewsletterSubscriber, which the password reset email'scustomervariable now uses.#14856
f508a38Thanks @damianlegawiec! - Preferences of the newmoneytype are shown with their currency's symbol in settings forms and as money in calculator summaries, instead of being guessed from the preference's name.PreferenceField.typedocuments themoneytype.
1.0.0-rc.1
Minor Changes
#14785
aa69c35Thanks @damianlegawiec! - Addedclient.emailTemplatesfor editing a store's customer email templates, email layout and shared partials: list and read them per language, save and discard drafts, preview with sample data, send a test email to yourself, publish, revert to Spree's default, and list or restore published revisions. Also addedEmailTemplate,EmailTemplateDraft,EmailTemplatePreviewandEmailTemplateRevision, andEmail*types (EmailOrder,EmailStore, ...) describing the data each customer email template renders with.#14800
fa4730aThanks @mad-eel! -orders.fulfillments.createaccepts an optionalsource_fulfillment_id, the only fulfillment to move units from. Without it, exchange and claim replacements are never moved, so naming the parcel is how a canceled replacement is sent again.#14816
06c5381Thanks @damianlegawiec! - Payment methods, payment method types and integration types now carrylogo_urlanddocs_url, the provider's logo and setup guide. Payment methods and their types also carrythird_party, true for methods backed by an external payment provider.PaymentMethodTypeis its own interface rather than an alias ofResourceTypeDefinition.#14837
3b80c52Thanks @damianlegawiec! - Changed every type value the APIs send or accept to a short name instead of a Ruby class name: delivery method, digital asset, payout, tax and pickup point providers (manual,internal,system,file), order routing strategies (rules), custom field definitionresource_type(product,category), tagtaggable_type, the owner and originator types on addresses, refunds and media usage, payment setup sessionpayment_source_type(credit_card), and type filters such astype_eqandreceivable_type_eq. Removedintegration_classfrom the provider listings and the deprecated custom fieldtypefield (usefield_type), and corrected the shipping labelowner_typetype to'fulfillment' | 'return'.#14799
c9d9a2fThanks @mad-eel! - Returns, claims and exchanges now give back the tax the customer paid. Return lines carryincluded_tax_total,additional_tax_total,tax_totalandrefund_amount(tax included), and returns carryrefund_tax_total. On a store whose prices include VAT, a return line'spre_tax_amountnow reads the price before tax rather than the gross price. Claim and exchange lines carry the tax on each half, tax lines name the return, claim or exchange line they belong to and whether they are acredit, Admin refunds carrytax_amount, and Seller order line items carryadditional_tax_total. Fees gain theexchangekind.#14799
c9d9a2fThanks @mad-eel! - Admin returns carrydisplay_refunded_total. A refunded return's card in the dashboard and the seller panel now shows what was actually refunded instead of what the return was worth, and names both when less went back, for example "Refunded $25.00 of $30.26".#14773
8f21572Thanks @damianlegawiec! - Added typed webhook events.@spree/sdk/webhooksnow maps every event Spree publishes to the record itsdatacarries, so checkingevent.namenarrowsevent.data, andconstructWebhookEventverifies a request and returns the typed event (optionally validated withwebhookEventSchemasfrom@spree/sdk/zod).WebhookEvent<Order>keeps working but is deprecated in favour ofWebhookEvent<'order.placed'>. The Admin SDK addsclient.webhookEvents.list(), and the dashboard's webhook event picker now reads that list instead of a hand-kept one.#14763
53d9925Thanks @damianlegawiec! - Added runtime Zod schemas to the Admin and Seller SDKs, exported from@spree/admin-sdk/zodand@spree/seller-sdk/zod, matching what@spree/sdk/zodalready offers for the Store API. Schemas for inline objects, unions and records are now precise instead of accepting any value, which also tightens a few Store SDK schemas (cart warnings, payment sources, product filters).
Patch Changes
- #14839
446d3cbThanks @damianlegawiec! - Changed permission subjects to short names:/mereturnsproduct,category,customerinstead of Ruby class names, and theSubjectconstants,<Can>checks and navigationsubjectentries use the same names. Plugins that pass class names ('Spree::Order') topermissions.can,<Can>or a navigation entry must switch to the short name ('order') or aSubjectconstant. Category checks now work for roles without full access.
1.0.0-beta.3
Minor Changes
- #14736
e601826Thanks @damianlegawiec! - Invitation listings no longer includeacceptance_url, because the link carries the token that accepts the invitation. Fetch it on demand withinvitations.acceptanceLink(id)(andsellers.invitations.acceptanceLink(sellerId, id)in the Admin SDK), which needs write access. The "Copy invitation link" actions in the dashboard and the seller panel now use it.
Patch Changes
#14702
349dddfThanks @damianlegawiec! -orders.createandorders.updateparams now includecompany_id, which the Admin API already accepted. Sending it makes a draft a company purchase;nullon update clears it.#14696
d065d0bThanks @damianlegawiec! -orders.refunds.createno longer acceptsreason_id. The Admin API only readsrefund_reason_id(matching theRefundresponse field), so areason_idwas silently dropped and the refund fell back to the store's first refund reason. The params are now typed asRefundCreateParams; passrefund_reason_idinstead.#14703
9e41f7dThanks @damianlegawiec! - Therefund_reason_iddocumentation now shows the refund reason ID prefix Spree actually uses (rr_…).#14727
a862b80Thanks @damianlegawiec! - The dashboard now refers to customers by their 6.0 class name,Spree::Customer, instead of the pre-6.0Spree::User. This fixes the Customers list's Tags filter, which always showed "No results", along with customer permission checks and customer custom fields.client.customFields('Spree::Customer', id)is now supported;'Spree::User'keeps working until 6.1.
1.0.0-beta.2
Patch Changes
#14671
20b5c2eThanks @damianlegawiec! - Acceptpreferred_always_include_confirm_stepwhen updating a store.#14644
6723b99Thanks @damianlegawiec! -auth.completeSetupacceptssample_data, which queues the demo catalog load once the admin account exists.
1.0.0-beta.1
Major Changes
#14442
4df88acThanks @damianlegawiec! - Rename the geography fields tocountry_codeandstate_codeacross the v3 API, replacingcountry_isoandstate_abbr. Addresses, stock locations, delivery zone members, markets, tax rates and tax exemption certificates all use the new names, on read and on write. Markets rename their list of countries fromcountry_isostocountry_codes.Addresses keep
country_isoandstate_abbras deprecated read fields and accepted write names for one release, so existing storefronts keep working; both are removed in 6.1. Every other resource moves outright.#14445
6d4fe64Thanks @damianlegawiec! - First-run setup asks which country the store sells from.completeSetupnow requirescountry_codeand accepts optionallocaleandcurrency. Both default to the country's own — its first official language and its currency — so a store's money and geography agree unless you say otherwise. An unrecognised currency is now rejected rather than quietly ignored.login,acceptInvitation,resetPasswordandcompleteSetupon the dashboard auth context now resolve with the session they establish, so callers can read the signed-in user without waiting for provider state.A new
auth.setupCountries()lists the countries a store can be set up in, each with the currency and official languages derived from it. Like the rest of the setup flow it needs no credentials, and stops answering once an admin account exists.#14458
da49f27Thanks @mad-eel! - Renamed stock items to stock levels.Spree 6.0 renames
Spree::StockItemtoSpree::StockLevel, and the admin API and SDK follow. There is no compatibility shim on the client side, so update your code before upgrading:client.stockItemsis nowclient.stockLevels, and it calls/stock_levelsinstead of/stock_items.- The
StockItemtype is nowStockLevel, andStockItemUpdateParamsis nowStockLevelUpdateParams. StockLevelUpdateParamsalso gainsreason, which labels a count correction in the stock history.client.stockMovementsis new, and reads the typed stock history behind those levels.- A variant's
stock_itemsarray is nowstock_levels, on both reads and writes. Subject.StockItemis nowSubject.StockLevelin@spree/dashboard-core. The old name stays as a deprecated alias for one release.- Prefixed ids change from
si_…tosl_…. Ids you stored earlier no longer resolve.
Webhook endpoints keep working: Spree publishes both
stock_level.*and the olderstock_item.*events for one release, so existing subscriptions keep firing. The dashboard's event picker now offers thestock_levelnames, and shows anystock_itemsubscription you already have under its Custom section. Move your subscriptions over before Spree 6.1, when the old names stop being published.#14461
32d4db9Thanks @damianlegawiec! - Store credits no longer carry a category.client.storeCreditCategoriesand theStoreCreditCategorytype are removed,category_idis no longer accepted or returned on customer store credits, and the dashboard's issue/edit store credit dialogs drop the category picker — the memo is the place to record why a credit was issued.
Minor Changes
#14410
fdd88ebThanks @mad-eel! - Add dashboard pages for business customers and tax configuration.Companies get a list and a detail page with their branches, tax registration and exemption certificates; a branch has its own page listing the buyers authorised to purchase for it. Customers gain the same tax registration panel on their profile. Tax rates get a settings page, and a market can now name the tax engine that prices it — showing what that engine cannot handle, so a merchant learns about a gap while configuring rather than from a tax bill.
The admin SDK gains the customer tax-identifier endpoints and
tax_provideron market params.#14430
9a4eb46Thanks @damianlegawiec! - Order numbers are now configurable from the dashboard.Settings → Store → Order numbers controls how document numbers are shaped: the numbering format (sequential or random), the order number prefix and suffix, and the value the sequence starts at. A live preview shows what the next number will look like.
Sequential numbering is the new default — orders count up from 1001 (
R1001,R1002) instead of carrying nine random digits. Merchants who would rather not disclose their order volume can switch the format back to random. Either way, changes apply to future orders only; numbers already issued never change.StoreUpdateParamsand theStoretype gainpreferred_document_number_format,preferred_order_number_prefix,preferred_order_number_suffixandpreferred_order_number_sequence_start.#14489
889a8cfThanks @damianlegawiec! - Media library. Every image and video in a store now lives in one place under Products → Media: browse it, search by file name, filter by type or by whether a file is in use, and upload files before deciding where they go. Picking a file from the library reuses it rather than copying it, so the same photo on three products is one file in storage.The library is reachable from everywhere media is set. The product gallery gains "Add from library", category, collection and seller image fields gain "Choose from library", and the rich text editor can embed an image in a description for the first time. Category and collection images now appear in the library too, so a file uploaded there can be reused anywhere else.
Every file shows where it is used before it is deleted, and deleting one that is still in use removes it from those places once the merchant confirms.
New in
@spree/admin-sdk: themediaresource (list,get,create,update,delete,usage),source_media_idon product media creation for reuse, andsigned_id,embed_url,filename,content_type,byte_sizeandattachedon the admin media payload.#14591
8e5dc20Thanks @damianlegawiec! - Volume pricing: quantity breaks, percentage tiers and a price-list CSV.A price list can now carry a ladder per variant — a unit price from each quantity up — edited as tier rows in the price spreadsheet, and a catalog's percentage adjustment can step by quantity too. The catalog's price column shows how many tiers a variant carries, with the ladder on hover and a note that fixed tiers set the price regardless of the percentage.
A price list's prices can be exported and imported as CSV, one rung per row keyed by SKU, from the list's own page and from the catalog that owns it. The import merges: rows in the file are written, a blank price removes that rung, and rungs the file does not mention are left alone. The admin SDK's price, price list and import types carry the new fields, and the import create call accepts the price list to merge into.
#14457
676aa0dThanks @damianlegawiec! - Product galleries can hold video.A media item now says what it is through
media_type.videois a file you upload and serve yourself;external_videois a YouTube or Vimeo link. Both sit in the same gallery as images and reorder alongside them.Spree reads the link when it is saved and rejects anything it cannot embed, so the media object comes back carrying
video_provider,video_embed_url,video_urlandposter_url— a storefront embeds a video without parsing links itself. A video's sized URLs resolve to its poster, so a gallery written for images still renders the right still.MediaCreateParamsandMediaUpdateParamsacceptmedia_type,external_video_url,poster_signed_idand the focal point. Thetypeparameter, which named an internal Ruby class, is gone —media_typereplaces it.A video carries a poster — the still shown before it plays. Upload one with
poster_signed_id, or leave it off and a YouTube link falls back to the provider's own image. Spree does not extract a frame from an uploaded file, so hosted video and Vimeo links want a poster.In the dashboard, video files upload through the same drop zone as images, an "Add video link" button takes a YouTube or Vimeo URL, and the media editor plays the video back and takes a poster the merchant uploads. The editor also gains a focal-point picker: click the spot on an image that must stay in frame when a storefront crops it.
Choosing which variants a media item represents happens in one place — the media editor on the product. The unmounted variant-side gallery picker has been removed; it was a second way to edit the same thing.
#14462
abc6e22Thanks @damianlegawiec! - Which address a sale's tax is computed from is now a store setting rather than a global one.preferred_tax_using_ship_addresscan be read and written through the Admin API, and merchants can change it under Settings → Store in the Payments card. The default is unchanged: tax follows the shipping address.
Patch Changes
#14521
9cee487Thanks @damianlegawiec! - New address forms pre-select the store's default country.The Admin store payload now includes
default_country_code(the same country the default market already answers). The shared address dialog uses it for new records and leaves an existing address's country alone.#14394
a8b11ecThanks @damianlegawiec! - Collections reach both SDKs.@spree/sdk(storefront):collections.list()/collections.get(idOrPermalink)— the flat, merchandising-driven groupings ("Summer Sale", "New Arrivals"), whether membership is curated by hand or maintained from rules.collections.products.list(idOrPermalink, params)— a collection's product listing page. Takes the same filters and sorts asproducts.list, and whensortis omitted the collection's ownsort_orderapplies, so a shopper sees the ordering the merchant chose (including their manual arrangement).in_collectiononProductListParams, for composing a collection filter into a wider product query.
@spree/admin-sdk(back office):collectionsCRUD, with reordering as a plain 1-basedpositionon update rather than a separate action — collections are a flat list. Nestedcollections.productscovers membership, ordering andreposition, plus custom fields and translations.collectionRules.types()enumerates the registered rule kinds, so a rule a plugin registers shows up without an SDK release.products.bulkAddToCollections/bulkRemoveFromCollections, andcollection_idson product create/update.ruleson a collection is expand-gated (?expand=rules), matchingcustom_fields— a listing no longer ships every collection's full rule set.hide_from_navis gone from the category params. Nothing read it.
#14417
7e35951Thanks @damianlegawiec! - Rich-text fields read as plain text plus HTML.Spree 6.0 stores rich text as sanitized HTML in plain text columns instead of Action Text. The write params are unchanged —
descriptionandinternal_notestill take the value, and that value is HTML.What changed is the read side:
internal_note_htmlis now readable onOrder, andinternal_note(plain text) onCustomer. Previously the order serializer returned only plain text and the customer serializer only HTML; both now return the pair.descriptionreturns tag-stripped plain text, with the markup underdescription_html. Hydrate an editor fromdescription_html, notdescription.
The field stores HTML, so send markup — a plain-text value with newlines in it renders as one run-on line.
#14376
a52a6daThanks @damianlegawiec! - Admin API additions from the 6.0 core rewrite:deliveryMethods.rulesCRUD anddeliveryMethods.ruleTypes()— delivery method eligibility rules (item total, weight).orders.discountCodes.create/delete— apply and remove coupon codes on draft orders with the storefront's pending semantics.expand=carton orders returns the originating cart (new adminCarttype); the embedded promotion summaries moved from thediscountskey toapplied_promotions(thediscountsname stays reserved for the typed money rows at/orders/:id/discounts).- Delivery methods accept
stock_location_idsfor pickup; delivery zones, delivery methods and stock locations are store-scoped. Ordergainscart_idandcoupon_code;DeliveryZone.membersrequiresexpand=members.
#14593
0f22450Thanks @Hemang-ai! - Preserve HTTP error statuses when a server returns an empty, non-JSON, or malformed error body. Avoid treating these responses as network failures, and allow admin and seller session recovery to handle unauthorized responses.
0.8.1
Patch Changes
#14353
8bf0dd0Thanks @ifizza! - Custom field definitions now support storefront search, sort, and filtering:CustomFieldDefinitionexposessearchable,sortable, andfilter_key, and create/update params acceptsearchable(short*text, long_text, number) andsortable(short_text, number). Product list requests accept the resultingcf*\*keys as bothsortvalues and Ransack filter predicates (e.g.q[cf_custom_material_i_cont]).#14357
f811d1eThanks @damianlegawiec! -AdminUsernow includes astoresarray — every store the user holds a role on ({ id, name, code }with prefixed IDs), powering the dashboard store switcher.#14363
705e515Thanks @damianlegawiec! - Breaking (Admin API):typeon imports and exports is now the API shorthand ("products","customers","product_translations","orders","gift_cards","coupon_codes","newsletter_subscribers") instead of the Ruby class name ("Spree::Imports::Products").ImportTypeandExportTypeare typed accordingly.Creating an import or export accepts either form, so a
typeread back from the API round-trips. Ransack filters (type_eq) are unaffected — they match the database column and still take the class name.Polymorphic type fields follow the same convention:
owner_typeon imports anditem_typeon import rows now return"store"/"product"rather than"Spree::Store"/"Spree::Product".
0.8.0
Minor Changes
- #14342
202d846Thanks @damianlegawiec! - Add per-channel order routing rule management.@spree/admin-sdkgainschannels.orderRoutingRules.{list,get,create,update,delete}(nested under/channels/:channel_id/order_routing_rules) plusorderRoutingRules.types()for rule-kind discovery; the adminStoretype now exposespreferred_order_routing_strategy. The dashboard's channel edit sheet embeds a routing-rules editor — drag-to-reorder priority, per-rule active toggles, an "Add rule" picker fed by the types endpoint (offering only kinds not yet on the channel; rule kinds are unique per channel), and schema-driven preference forms for rule kinds that declare preferences. The editor renders only when the channel's effective routing strategy is Rules.Subject.OrderRoutingRuleis available for permission checks.
0.7.0
Minor Changes
- Support channel binding on publishable API keys.
apiKeys.create()accepts an optionalchannel_id, andApiKeynow carrieschannel_id. A bound key always resolves its channel server-side and rejects requests naming a different one; the binding is create-only and immutable. Omitchannel_idfor a store-wide key.
0.6.1
Patch Changes
Customersupports the newnewsletter_subscriberexpand — passexpand: ['newsletter_subscriber']tocustomers.get/customers.listto include the customer's store-scoped newsletter subscription.
0.6.0
This is the Admin API surface the 5.6 React Dashboard consumes — hosts installing @spree/[email protected] from the registry need this version; 0.5.0 lacks exports the dashboard imports.
Minor Changes
Add asynchronous CSV imports.
client.imports.create({ type, attachment })queues an import from a direct-uploaded CSV (pass thesigned_idfromclient.directUploads.create()); the response is in themappingstate and carries the type'sschema_fields, the file'scsv_headers, asample_row, and auto-assigned columnmappings. Adjust mappings if needed and callclient.imports.completeMapping(id, { mappings })to start background processing, then pollclient.imports.get(id)—rows_count,completed_rows_count, andfailed_rows_countdrive progress until the terminalcompleted/failedstatus. Failed rows (with the raw CSVdataand per-rowvalidation_errors) are listed viaclient.imports.rows.list(id, { status_eq: 'failed' })and can be re-processed withclient.imports.retryFailedRows(id). Pass an optionalresults_urlon create (validated against the store's allowed origins) and the import-done email links back to your admin's imports view with?import=<id>appended. NewImport,ImportRow,ImportMapping,ImportType,ImportCreateParams, andImportCompleteMappingParamstypes describe these shapes.Add translation management for translatable resources.
client.translatableResources.list()discovers every translatable resource type, its translatable fields, and whether each one exposes a dedicated read route (readable);client.locales.list()returns the locales a merchant can translate content into for the current store. Per-resource reads are available viaclient.products.translations.get(id)andclient.optionTypes.translations.get(id), each returning the full locale × field matrix plus any nested translatable children (e.g. an option type's option values) in one request. All writes go throughclient.translations.batch(entries)— a single atomic endpoint that upserts translations across many records of any registered type, so an option type and all its option values can be translated in one save. NewLocale,TranslatableResource,TranslatableField,ResourceTranslations,ResourceTranslationsNode, andTranslationBatchEntrytypes describe these shapes.Add
orders.fulfillments.createfor manually registering fulfillments on completed orders (POST /orders/:order_id/fulfillments). Supports external carrier / 3PL sync: pick the stock location, carrier (delivery_method_id), tracking number, and line item quantities (items, omitted = everything not yet shipped), and passstatus: 'shipped'to register an already-shipped fulfillment. Adds theFulfillmentCreateParamstype.FulfillmentUpdateParams.selected_delivery_rate_idis now honored by the Admin API (previously the server expected a different field name and ignored it).orders.fulfillments.createnow accepts an optionalcost(explicit shipping cost, e.g. the 3PL price — frozen exactly onstatus: 'shipped'registrations; note it changes the order total and payment state). Whendelivery_method_idis omitted, the new fulfillment now inherits the delivery method and cost of the source fulfillment(s) it fully drains instead of defaulting to the lowest-cost rate.Add pre-order management to the Admin API.
Variantnow exposes the editablepreorderableflag,preorder_ships_at(the "ships by" date), andbackorder_limit(the universal oversell cap — units sellable beyond available stock as backorders or pre-orders;null= unlimited), alongside the computedpreorderstate;ProductandLineItemgainpreorder+preorder_ships_at.ProductVariantInput,VariantCreateParams, andVariantUpdateParamsacceptpreorderable,preorder_ships_at, andbackorder_limit, so a variant can be flagged for pre-order and capped in a single write.Expose customer group membership on the Customer resource.
Customer.customer_group_idsnow always returns the prefixed group IDs a customer belongs to (the fullcustomer_groupsobjects remain available viaexpand), andCustomerCreateParams/CustomerUpdateParamsacceptcustomer_group_idsto replace a customer's group membership in a singlePATCH /customers/{id}— no separate add/remove calls needed.Add self-service profile updates for the authenticated admin.
client.me.update(params)(PATCH /me) lets the signed-in admin change their ownselected_locale(admin UI display language),first_name, andlast_namewithout going through the store-scoped staff-management endpoint. TheMeResponse.usershape now includesselected_locale, and a newMeUpdateParamstype describes the writable fields.Expose
Store.available_locales— the full canonical set of locale codes a merchant may translate content into, independent of the store's currently-configuredsupported_locales. Lets locale pickers offer any supported locale instead of only ones already in use.Expose the store-wide gated storefront defaults on the Store resource.
Store.preferred_storefront_access(public,prices_hidden, orlogin_required) andStore.preferred_guest_checkoutare now serialized, andStoreUpdateParamsaccepts both — letting apps read and configure the store-level fallback that channels inherit when they don't set their own posture.
Patch Changes
ExportCreateParamsaccepts an optionalresults_url(validated against the store's allowed origins) — the export-done email uses it as its download button target instead of relying on the legacy Rails admin's routes.Fulfillment
trackingnow accepts a fullhttps://tracking link — the API serves it back astracking_urlunchanged instead of templating it into the delivery method's tracking URL. Useful when an external system (3PL, courier API) provides the complete link.Regenerated types: fixes
created_at/updated_aton Country, State, and other resources previously typedunknowntostring. Admin money fields remain non-nullable — storefront price gating never applies to the Admin API.
0.5.0
Minor Changes
Align the variant write params with the v3 API: variants are priced exclusively through the per-currency
pricesarray — the legacy singularcompare_at_pricefield is no longer accepted.Note on bump type:
@spree/admin-sdkis on a 0.x version line (nextdist-tag, Developer Preview). Per Changesets convention, breaking changes on 0.x packages bump the minor — moving tomajorwould mean 1.0.0 and signal API stability we do not yet guarantee. The changes below are breaking; coordinated with the server-side change shipping in Spree 6.0.Breaking changes:
VariantCreateParamsandVariantUpdateParamsno longer acceptcompare_at_price. Set the compare-at price per currency viaprices: [{ currency, amount, compare_at_amount }]instead.VariantCreateParams.optionsis now required. The standalonevariants.createendpoint always creates a non-master variant, which must declare at least one option pair (e.g. size + color) or creation fails with422.ProductCreateParams.variants/ProductUpdateParams.variantsnow use the newProductVariantInputtype instead ofVariantCreateParams[]/VariantUpdateParams[]. A nested variant entry keepsoptionsoptional: an options-less entry upserts onto the product's default variant (the simple, no-options product case).
0.4.0
Minor Changes
- API key scopes are now immutable after creation.
apiKeys.update()accepts onlyname—ApiKeyUpdateParamsno longer includesscopesand now requiresname(a breaking change to the public type). AddedapiKeys.current()to describe the authenticating key, including its live scopes.
0.3.0
Minor Changes
- Add the top-level
pricesshorthand toProductCreateParams/ProductUpdateParamsfor simple (no-options) products — prices ship alongsidename/statusand forward to the product's sole variant, so callers don't have to construct avariantsarray. Widen the refundamount(orders.refunds.create) andOrderCancelParams.refund_amounttostring | numberfor consistency with every other monetary field, and update examples to send amounts as strings so localized input ("1.299,00") round-trips through the backend's locale-aware parsing.
0.2.0
Minor Changes
Cookie-backed admin authentication. The refresh token now lives in an
HttpOnlysigned cookie scoped to/api/v3/admin/authinstead of being returned in JSON; the access token is the only thing the SPA holds in memory. This eliminates the most attractive XSS target on the admin SPA and adds a real server-side logout that destroys the refresh-token row.CSRF protection is provided by the combination of the cookie's
SameSiteattribute and the existingSpree::AllowedOriginallowlist enforced viaRack::Cors— no separate CSRF token is issued or required by the SDK.Note on bump type:
@spree/admin-sdkis on a 0.x version line (nextdist-tag, Developer Preview). Per semver §4 and Changesets convention, breaking changes on 0.x packages bump the minor — moving tomajorwould mean 1.0.0 and signal API stability we do not yet guarantee. The changes below are breaking; coordinated with the server-side change shipping in Spree 5.5.Breaking changes:
AuthTokensno longer containsrefresh_token. The shape is{ token, user }.client.auth.refresh()takes no arguments — it reads the refresh-token cookie. Previously it required{ refresh_token }in the body.- New
client.auth.logout()— POSTs to/api/v3/admin/auth/logout, which destroys the refresh-token row server-side and clears the auth cookie. Idempotent. createAdminClient()now defaults tocredentials: 'include'so cookies flow on cross-origin requests. Override viacreateAdminClient({ credentials: 'omit' })if needed.- The
secretKey || jwtTokenconstructor guard has been relaxed: a cookie-auth SPA may start with neither and bootstrap by callingauth.refresh()immediately. Server-to-server callers should still passsecretKey.
When using
baseUrl: ''(e.g. with a Vite dev proxy), the SDK now resolves the relative path againstwindow.location.originsonew URLdoesn't throw.Admin CSV exports — bring back filtered CSV downloads of products, orders, customers, etc. that the legacy Rails admin supported.
- New
client.exportsresource withlist / get / create / delete. - New
ExportCreateParams/ExportTyperequest types andExportentity type. Export.download_urlis the path to a server-side download endpoint (GET /api/v3/admin/exports/:id/download) that 303s to a freshly-signed ActiveStorage URL — assign it towindow.location.hrefto trigger the download.Export.doneflips totrueonce the background job finishes generating and attaching the CSV; clients should pollget(id)until then.search_paramsaccepts the same Ransack predicate shape ({ name_cont, price_gt, … }) used on list endpoints, so toolbar filter state can be forwarded as-is.
- New
Custom Fields CRUD API + token-based
field_type.- New
client.{products,variants,orders,customers,categories,optionTypes}.customFieldsaccessors withlist / get / create / update / delete. - New top-level
client.customFieldDefinitionsaccessor with full CRUD. - New generic escape hatch
client.customFields(ownerType, ownerId)for plugin-defined parents that don't have a first-class accessor. CustomField.field_typeandCustomFieldDefinition.field_typeare now string-literal unions ('short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json' | (string & {})) instead of plainstring. Built-ins narrow + autocomplete; plugin tokens still type-check.CustomFieldretains the legacytypefield (Ruby STI class name) alongside the newfield_typetoken. The TypeScript type is annotated with@deprecatedso editors surface the migration tip on hover; eslint withno-deprecatedwill flag references. Migrate tofield_type;typewill be removed in a future minor.- New
CustomFieldDefinitiontype exported from the package. - Includes the
Spree::CustomField/Spree::CustomFieldDefinitionconstant aliases on the server side; no naming changes to existing models or table layout.
- New
Sprint 3: utility CRUD writes for tax categories, stock items, stock transfers, and payment methods.
client.taxCategoriesgainsget / create / update / delete. Backed by/api/v3/admin/tax_categories. The serializer now exposesdescriptionalongsidename,tax_code, andis_default. Settingis_default: trueon create or update auto-demotes the previous default.client.stockItemsis new withlist / get / update / delete. Adjustcount_on_handandbackorderableon existing variant/location pairings. Stock items are auto-created when a variant lands at a stock location, so there's nocreatehere — use the variants and stock-locations endpoints for that flow. Filterable via Ransack oncount_on_hand,stock_location_id, andvariant_id.client.stockTransfersis new withlist / get / create / delete. Backed by/api/v3/admin/stock_transfers. The create body takes avariants: [{ variant_id, quantity }]array; passsource_location_idfor a transfer between two locations or omit it to record an external seller receive at the destination. The model fans the payload out acrossstock_movementsand adjusts source/destinationcount_on_handatomically.client.paymentMethodsgainscreate / update / delete / types. The create body requirestype(the fully-qualified STI subclass, e.g.'Spree::PaymentMethod::Check'); unknown types return a 422 withunknown_payment_method_type. New payment methods are scoped to the current store automatically. The serializer now exposesdisplay_onandpositionon top of the existingname,description,type,active, andauto_capture.client.paymentMethods.types()returns the registered subclasses as[{ type, label, description }]so admin UIs can render a provider dropdown without hard-coding class names.
Provider-specific configuration (Stripe API keys, PayPal credentials, etc.) is not part of this release — that lands with the universal preferences form in the next sprint.
Sprint 4: full admin promotion stack — promotions, actions, rules, and coupon codes.
client.promotionsis new withlist / get / create / update / delete. MirrorsSpree::Promotion:name,description,code,starts_at,expires_at,usage_limit,match_policy,kind('coupon_code' | 'automatic'),multi_codes+number_of_codes+code_prefixfor batch coupon generation,path,advertise,promotion_category_id, andstore_ids.client.promotions.actions(nested) handles the STI subclass pattern:list / get / create / update / deleteon/promotions/:id/promotion_actions. The create body takes atype(the fully-qualified subclass like'Spree::Promotion::Actions::FreeShipping') plus apreferences: { ... }hash that round-trips through the typed setters declared on the subclass.client.promotions.rules(nested) is the same shape forSpree::PromotionRulesubclasses (Currency, Country, ItemTotal, Product, Taxon, etc.).client.promotions.couponCodes(nested) is read-only —list / get. Coupon codes are server-generated based on the promotion'smulti_codessettings.client.promotionActions.types()andclient.promotionRules.types()are top-level discovery endpoints. Each returns{ data: ResourceTypeDefinition[] }where each entry is{ type, label, description, preference_schema }. Thepreference_schemadescribes the configurable knobs for a given subclass —[{ key, type, default }]— so admin UIs can render generic configuration forms without hard-coding per-subclass field lists.client.paymentMethods.create / updatenow accept an optionalpreferenceshash, matching the same round-trip pattern. The serializer payload also gainspreferences(current values) andpreference_schema(shape).New shared types:
PreferenceField,ResourceTypeDefinition. The previously-shippedPaymentMethodTypeis now an alias ofResourceTypeDefinition.
Staff and API key management.
- New
client.adminUsersaccessor withlist / get / update / delete. Listing is scoped to admin users with at least one role assignment on the current store.deleteremoves the per-store role assignment rather than deleting the global account, so the user keeps access to any other stores. - New
client.invitationsaccessor withlist / get / create / delete / resend. Invitations carry anemail+ prefixedrole_id; on accept, a per-storeRoleUseris created.resendissues a fresh token and re-dispatches the invitation email. - New
client.apiKeysaccessor withlist / get / create / update / delete / revoke. Supports bothpublishable(storefront) andsecret(server-to-server) keys. The plaintext token for secret keys is delivered exactly once on the create response — store it client-side immediately because subsequent reads expose onlytoken_prefix.revokemarks the key revoked while preserving the row for audit. - New
client.rolesaccessor withlist / get. Read-only — used to populate the role picker on the staff invite/edit forms. - New
client.auth.lookupInvitation(id, token)andclient.auth.acceptInvitation(id, token, params). Public (unauthenticated) endpoints that drive the SPA invitation acceptance screen —lookupreturns the safe-to-render context (store, role, inviter,invitee_exists) so the page can pick between sign-in (existing account) and signup (new account);acceptcreates the user if needed, marks the invitation accepted, and issues a JWT + refresh-token cookie identical toauth.login. Invitationnow carriesacceptance_url— the shareable link the SPA's "Copy invitation link" action and the invitation email both use.- New types:
ApiKey,Invitation,Role,InvitationLookup.AdminUsernow includes arolesfield with the role assignments scoped to the current store. - New params types:
ApiKeyCreateParams,ApiKeyUpdateParams,InvitationCreateParams,InvitationAcceptParams,AdminUserUpdateParams.
- New
Stock location management.
- New
client.stockLocationsaccessor withlist / get / create / update / delete. Backed by/api/v3/admin/stock_locations. Listing supports the standard Ransack filters (name_cont,active_eq,kind_eq,pickup_enabled_eq, etc.) plus default ordering bydefault desc, name ascso the default location surfaces first. - New params types:
StockLocationCreateParams,StockLocationUpdateParams. Address fields usecountry_iso(ISO-3166 alpha-2 country code, e.g.'US') andstate_abbr(state/province abbreviation, e.g.'NY') — the same opaque handles used everywhere else in the API for countries and states. - The
StockLocationentity gains the 6.0 fulfillment-and-delivery columns:kind('warehouse' | 'store' | 'fulfillment_center', open string — plugins can register custom kinds),pickup_enabled,pickup_stock_policy('local'keeps stock at the location only;'any'allows transfer-in / ship-to-store),pickup_ready_in_minutes, andpickup_instructions. These are the storefront-facing fields the upcoming pickup-fulfillment flow surfaces at checkout. Seedocs/plans/6.0-fulfillment-and-delivery.mdfor the wider context. - Admin serializer now also exposes
admin_name,address2,state_name,phone,company, pluscreated_at/updated_at.
- New
Store credit category lookups + richer store credit payloads.
- New
client.storeCreditCategoriesaccessor withlist / get. Backed by/api/v3/admin/store_credit_categories. Read-only — categories are configured at the store level and used to classify issued store credits ("Goodwill", "Refund", "Gift Card", etc.). Ransack filtering supported (e.g.q[name_cont]). - New
StoreCreditCategorytype exported from the package:{ id, name, non_expiring, created_at, updated_at }.non_expiringreflects whether the category name appears inSpree::Config[:non_expiring_credit_types]. - The admin
StoreCreditshape now includescategory_id,category_name, andmemo.category_idround-trips with the categories endpoint above;category_nameis delegated from the associated category for display without an extra fetch;memois the merchant-visible note set when the credit was issued. - The existing
client.customers.storeCredits.{create,update}endpoints have not changed shape —category_idandmemowere already accepted on write; this release only surfaces them on read.
- New
Add provider-dispatched login.
client.auth.login()now accepts third-party identity-provider payloads (e.g.{ provider: 'okta', token: '<jwt>' }) in addition to the existing{ email, password }shape —LoginCredentialsis now a discriminated union ofEmailPasswordLogin | ProviderLogin, both newly exported. Pairs with the server-side strategy registry atSpree.admin_authentication_strategies. Existing email/password calls are unchanged.
Patch Changes
Expose
Product.option_valuesin the Admin API.The
Producttype now includes an optionaloption_values: Array<OptionValue>field, listing the option values that are actually in use across the product's variants — useful for rendering option pickers and variant matrices in the admin without iterating over every variant.