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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added dedicated Markets API
Damian Legawiecd84c13a1d034
diff --git a/spree/api/app/controllers/spree/api/v3/store/markets/countries_controller.rb b/spree/api/app/controllers/spree/api/v3/store/markets/countries_controller.rbnew file mode 100644index 0000000000..5f473b5272--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/store/markets/countries_controller.rb@@ -0,0 +1,39 @@+module Spree+ module Api+ module V3+ module Store+ module Markets+ class CountriesController < Store::BaseController+ before_action :load_market++ # GET /api/v3/store/markets/:market_id/countries+ def index+ countries = @market.countries.order(:name)++ render json: {+ data: countries.map { |country| serialize_country(country) }+ }+ end++ # GET /api/v3/store/markets/:market_id/countries/:id+ def show+ country = @market.countries.find_by!(iso: params[:id].upcase)++ render json: serialize_country(country)+ end++ private++ def load_market+ @market = current_store.markets.find_by_prefix_id!(params[:market_id])+ end++ def serialize_country(country)+ Spree.api.market_country_serializer.new(country, params: serializer_params).to_h+ end+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/controllers/spree/api/v3/store/markets_controller.rb b/spree/api/app/controllers/spree/api/v3/store/markets_controller.rbnew file mode 100644index 0000000000..03c9a03a57--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/store/markets_controller.rb@@ -0,0 +1,42 @@+module Spree+ module Api+ module V3+ module Store+ class MarketsController < Store::BaseController+ # GET /api/v3/store/markets+ def index+ markets = current_store.markets.includes(:countries).order(:position)++ render json: {+ data: markets.map { |market| serialize_market(market) }+ }+ end++ # GET /api/v3/store/markets/:id+ def show+ market = current_store.markets.includes(:countries).find_by_prefix_id!(params[:id])++ render json: serialize_market(market)+ end++ # GET /api/v3/store/markets/resolve?country=DE+ def resolve+ country_iso = params[:country]&.upcase+ country = Spree::Country.find_by!(iso: country_iso)+ market = current_store.market_for_country(country)++ raise ActiveRecord::RecordNotFound unless market++ render json: serialize_market(market)+ end++ private++ def serialize_market(market)+ Spree.api.market_serializer.new(market, params: serializer_params.merge(includes: include_list + ['countries'])).to_h+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/country_serializer.rb b/spree/api/app/serializers/spree/api/v3/country_serializer.rbindex 471dd87cef..e9eda9bb17 100644--- a/spree/api/app/serializers/spree/api/v3/country_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/country_serializer.rb@@ -10,7 +10,9 @@ module Spreestates_required: :boolean, zipcode_required: :boolean,currency: [:string, nullable: true],default_locale: [:string, nullable: true],- supported_locales: [:string, multi: true]+ supported_locales: [:string, multi: true],+ tax_inclusive: :boolean,+ market: [:object, nullable: true, properties: { id: :string, name: :string }]attributes :iso, :iso3, :name, :states_required, :zipcode_required@@ -26,6 +28,15 @@ module Spreecountry.market_supported_localesend+ attribute :tax_inclusive do |country|+ country.current_market&.tax_inclusive || false+ end++ attribute :market do |country|+ m = country.current_market+ m ? { id: m.prefixed_id, name: m.name } : nil+ end+many :states,resource: Spree.api.state_serializer,if: proc { params[:includes]&.include?('states') }diff --git a/spree/api/app/serializers/spree/api/v3/market_country_serializer.rb b/spree/api/app/serializers/spree/api/v3/market_country_serializer.rbnew file mode 100644index 0000000000..7f6c45e421--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/market_country_serializer.rb@@ -0,0 +1,21 @@+module Spree+ module Api+ module V3+ # Lightweight country serializer for use when nested inside MarketSerializer.+ # Omits market-derived fields (currency, locale) since the parent market already has them.+ class MarketCountrySerializer+ include Alba::Resource+ include Typelizer::DSL++ typelize iso: :string, iso3: :string, name: :string,+ states_required: :boolean, zipcode_required: :boolean++ attributes :iso, :iso3, :name, :states_required, :zipcode_required++ many :states,+ resource: Spree.api.state_serializer,+ if: proc { params[:includes]&.include?('states') }+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/market_serializer.rb b/spree/api/app/serializers/spree/api/v3/market_serializer.rbnew file mode 100644index 0000000000..da1215dc19--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/market_serializer.rb@@ -0,0 +1,23 @@+module Spree+ module Api+ module V3+ class MarketSerializer < BaseSerializer+ typelize name: :string, currency: :string,+ default_locale: :string,+ supported_locales: [:string, multi: true],+ tax_inclusive: :boolean,+ default: :boolean++ attributes :id, :name, :currency, :default_locale, :tax_inclusive, :default++ attribute :supported_locales do |market|+ market.supported_locales_list+ end++ many :countries,+ resource: Spree.api.market_country_serializer,+ if: proc { include?(:countries) }+ end+ end+ end+enddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 16b2dc7046..83e98618d2 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -11,6 +11,14 @@ Spree::Core::Engine.add_routes do# Storeresource :store, only: [:show]+ # Markets+ resources :markets, only: [:index, :show] do+ collection do+ get :resolve+ end+ resources :countries, only: [:index, :show], controller: 'markets/countries'+ end+# Countries, Currencies, Locales (flat, market-aware)resources :countries, only: [:index, :show]resources :currencies, only: [:index]diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex 888aef918c..e23636f9a3 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -107,6 +107,8 @@ module Spreeaddress_serializer: 'Spree::Api::V3::AddressSerializer',customer_serializer: 'Spree::Api::V3::CustomerSerializer',country_serializer: 'Spree::Api::V3::CountrySerializer',+ market_serializer: 'Spree::Api::V3::MarketSerializer',+ market_country_serializer: 'Spree::Api::V3::MarketCountrySerializer',state_serializer: 'Spree::Api::V3::StateSerializer',store_serializer: 'Spree::Api::V3::StoreSerializer',wishlist_serializer: 'Spree::Api::V3::WishlistSerializer',diff --git a/spree/api/spec/integration/spree/api/v3/store/markets_spec.rb b/spree/api/spec/integration/spree/api/v3/store/markets_spec.rbnew file mode 100644index 0000000000..3050ef7af4--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/store/markets_spec.rb@@ -0,0 +1,203 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Markets API', type: :request, swagger_doc: 'api-reference/store.yaml' do+ include_context 'API v3 Store'++ let!(:usa) { Spree::Country.find_by(iso: 'US') || create(:country, iso: 'US', name: 'United States', states_required: true) }+ let!(:california) { Spree::State.find_by(abbr: 'CA', country: usa) || create(:state, country: usa, name: 'California', abbr: 'CA') }+ let!(:germany) { Spree::Country.find_by(iso: 'DE') || create(:country, iso: 'DE', name: 'Germany', states_required: false) }+ let!(:france) { Spree::Country.find_by(iso: 'FR') || create(:country, iso: 'FR', name: 'France', states_required: false) }++ let!(:na_market) { create(:market, :default, name: 'North America', store: store, countries: [usa], currency: 'USD', default_locale: 'en', supported_locales: 'en,es') }+ let!(:eu_market) { create(:market, name: 'Europe', store: store, countries: [germany, france], currency: 'EUR', default_locale: 'de', supported_locales: 'de,en,fr', tax_inclusive: true) }++ let(:market_country_schema) do+ {+ type: :object,+ properties: {+ iso: { type: :string },+ iso3: { type: :string },+ name: { type: :string },+ states_required: { type: :boolean },+ zipcode_required: { type: :boolean }+ },+ required: %w[iso iso3 name states_required zipcode_required]+ }+ end++ let(:market_schema) do+ {+ type: :object,+ properties: {+ id: { type: :string },+ name: { type: :string },+ currency: { type: :string },+ default_locale: { type: :string },+ supported_locales: { type: :array, items: { type: :string } },+ tax_inclusive: { type: :boolean },+ default: { type: :boolean },+ countries: { type: :array, items: market_country_schema }+ },+ required: %w[id name currency default_locale supported_locales tax_inclusive default countries]+ }+ end++ path '/api/v3/store/markets' do+ get 'List markets' do+ tags 'Markets'+ produces 'application/json'+ security [api_key: []]+ description 'Returns all markets for the current store with their countries, currency, locales, and tax configuration.'++ sdk_example <<~JS+ const markets = await client.store.markets.list()+ JS++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true++ response '200', 'markets found' do+ let(:'x-spree-api-key') { api_key.token }++ schema type: :object,+ properties: {+ data: { type: :array }+ },+ required: ['data']++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['data'].size).to eq(2)++ na = data['data'].find { |m| m['name'] == 'North America' }+ expect(na['currency']).to eq('USD')+ expect(na['default_locale']).to eq('en')+ expect(na['supported_locales']).to match_array(['en', 'es'])+ expect(na['tax_inclusive']).to eq(false)+ expect(na['default']).to eq(true)+ expect(na['countries'].size).to eq(1)+ expect(na['countries'].first['iso']).to eq('US')++ eu = data['data'].find { |m| m['name'] == 'Europe' }+ expect(eu['currency']).to eq('EUR')+ expect(eu['tax_inclusive']).to eq(true)+ expect(eu['default']).to eq(false)+ expect(eu['countries'].size).to eq(2)+ end+ end++ response '401', 'unauthorized' do+ let(:'x-spree-api-key') { 'invalid' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/store/markets/{id}' do+ get 'Get a market' do+ tags 'Markets'+ produces 'application/json'+ security [api_key: []]+ description 'Returns a single market by prefixed ID with its countries, currency, locales, and tax configuration.'++ sdk_example <<~JS+ const market = await client.store.markets.get('mkt_xxx')+ JS++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :id, in: :path, type: :string, required: true,+ description: 'Market prefixed ID (e.g., "mkt_k5nR8xLq")'++ response '200', 'market found' do+ let(:'x-spree-api-key') { api_key.token }+ let(:id) { eu_market.prefixed_id }++ schema type: :object++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(eu_market.prefixed_id)+ expect(data['name']).to eq('Europe')+ expect(data['currency']).to eq('EUR')+ expect(data['tax_inclusive']).to eq(true)+ expect(data['countries'].size).to eq(2)+ end+ end++ response '404', 'market not found' do+ let(:'x-spree-api-key') { api_key.token }+ let(:id) { 'mkt_nonexistent' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/store/markets/resolve' do+ get 'Resolve market by country' do+ tags 'Markets'+ produces 'application/json'+ security [api_key: []]+ description 'Determine which market applies for a given country ISO code. Useful for auto-selecting the correct currency and locale when a customer\'s location is known.'++ sdk_example <<~JS+ const market = await client.store.markets.resolve('DE')+ JS++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :country, in: :query, type: :string, required: true,+ description: 'Country ISO 3166-1 alpha-2 code (e.g., "DE", "US")'++ response '200', 'market resolved' do+ let(:'x-spree-api-key') { api_key.token }+ let(:country) { 'DE' }++ schema type: :object++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(eu_market.prefixed_id)+ expect(data['name']).to eq('Europe')+ expect(data['currency']).to eq('EUR')+ expect(data['tax_inclusive']).to eq(true)+ end+ end++ response '404', 'no market for country' do+ let(:'x-spree-api-key') { api_key.token }+ let(:country) { 'JP' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/store/markets/{market_id}/countries' do+ get 'List countries in a market' do+ tags 'Markets'+ produces 'application/json'+ security [api_key: []]+ description 'Returns countries belonging to a specific market. Use this for address form country dropdowns during checkout.'++ sdk_example <<~JS+ const countries = await client.store.markets.countries.list('mkt_xxx')+ JS++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :market_id, in: :path, type: :string, required: true,+ description: 'Market prefixed ID'++ response '200', 'countries found' do+ let(:'x-spree-api-key') { api_key.token }+ let(:market_id) { eu_market.prefixed_id }++ schema type: :object,+ properties: {