Skip to content

armgit / spree

Public Imported from GitHub
0

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

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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/markets_controller.rb b/spree/api/app/controllers/spree/api/v3/store/markets_controller.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/serializers/spree/api/v3/country_serializer.rb b/spree/api/app/serializers/spree/api/v3/country_serializer.rb
index 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 Spree
states_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 Spree
country.market_supported_locales
end
+ 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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/serializers/spree/api/v3/market_serializer.rb b/spree/api/app/serializers/spree/api/v3/market_serializer.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 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
# Store
resource :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.rb
index 888aef918c..e23636f9a3 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -107,6 +107,8 @@ module Spree
address_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.rb
new file mode 100644
index 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: {