Skip to main content

Documentation Index

Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt

Use this file to discover all available pages before exploring further.

Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the Spree API docs. For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the Store API tutorial.

​
Customizing JSON Responses

Spree uses Alba serializers to build API v3 responses. You can replace any serializer via Spree Dependencies.

​
Adding Custom Attributes

Let’s say you want to add a my_custom_attribute column to the Product API response. Create a custom serializer that inherits from the core one:
app/serializers/my_app/product_serializer.rb
module MyApp
  class ProductSerializer < Spree::Api::V3::ProductSerializer
    attribute :my_custom_attribute
  end
end
Register it in config/initializers/spree.rb: 
Spree::Api::Dependencies.product_serializer = 'MyApp::ProductSerializer'
Restart the server and the Product API will include your new attribute.

​
Adding an Association

Let’s say you’ve created a Spree::Brand model that belongs to Product (see the tutorial for the full example). Create a serializer for the new model:
app/serializers/spree/api/v3/brand_serializer.rb
module Spree
  module Api
    module V3
      class BrandSerializer < BaseSerializer
        typelize name: :string, slug: [:string, nullable: true]

        attributes :name, :slug
      end
    end
  end
end
Then subclass the Product serializer to include the brand association:
app/serializers/my_app/product_serializer.rb
module MyApp
  class ProductSerializer < Spree::Api::V3::ProductSerializer
    typelize brand_id: [:string, nullable: true]

    attribute :brand_id do |product|
      product.brand&.prefixed_id
    end

    one :brand,
        resource: Spree::Api::V3::BrandSerializer,
        if: proc { expand?('brand') }
  end
end
Register it in config/initializers/spree.rb: 
Spree::Api::Dependencies.product_serializer = 'MyApp::ProductSerializer'
The brand data is available via ?expand=brand: 
GET /api/v3/store/products/prod_86Rf07xd4z?expand=brand

​
Serializer Dependency Keys

Here are the most commonly customized v3 serializers:
KeyDefault
product_serializerSpree::Api::V3::ProductSerializer
variant_serializerSpree::Api::V3::VariantSerializer
cart_serializerSpree::Api::V3::CartSerializer
order_serializerSpree::Api::V3::OrderSerializer
line_item_serializerSpree::Api::V3::LineItemSerializer
category_serializerSpree::Api::V3::CategorySerializer
customer_serializerSpree::Api::V3::CustomerSerializer
address_serializerSpree::Api::V3::AddressSerializer
payment_serializerSpree::Api::V3::PaymentSerializer
fulfillment_serializerSpree::Api::V3::FulfillmentSerializer
See Spree::Api::ApiDependencies for the full list.

​
Adding New Endpoints

​
Controller

Inherit from Spree::Api::V3::Store::ResourceController for Store API endpoints:
app/controllers/spree/api/v3/store/brands_controller.rb
module Spree
  module Api
    module V3
      module Store
        class BrandsController < ResourceController
          protected

          def model_class
            Spree::Brand
          end

          def serializer_class
            Spree::Api::V3::BrandSerializer
          end

          def scope
            Spree::Brand.all
          end
        end
      end
    end
  end
end
The base ResourceController provides:
FeatureHow
PaginationPagy — ?page=2&limit=25
FilteringRansack — ?q[name_cont]=nike
SortingJSON:API style — ?sort=-name
AuthorizationCanCanCan
Prefixed IDsStripe-style — brand_k5nR8xLq
Override these methods to customize:
MethodPurpose
model_classActiveRecord model (required)
serializer_classAlba serializer (required)
scopeBase query — add .where() to filter
find_resourceCustom ID lookup (slug fallback, etc.)
permitted_paramsCustom strong params
collection_includesEager loading for index

​
Routes

Add routes in your app’s config/routes.rb: 
Spree::Core::Engine.add_routes do
  namespace :api, defaults: { format: 'json' } do
    namespace :v3 do
      namespace :store do
        resources :brands, only: [:index, :show]
      end
    end
  end
end

​
Permitted Attributes

For endpoints that accept writes (create/update), add your attributes:
config/initializers/spree.rb
Spree::PermittedAttributes.brand_attributes = [:name, :slug, :description, :logo]
Or override permitted_params in the controller: 
def permitted_params
  params.permit(:name, :slug, :description, :logo)
end

​
Consuming Custom Endpoints with the SDK

See the SDK tutorial for how to call custom endpoints from TypeScript and extend the generated types.