Customizing the Spree API - Spree Commerce documentation

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 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

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

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:

Key	Default
`product_serializer`	`Spree::Api::V3::ProductSerializer`
`variant_serializer`	`Spree::Api::V3::VariantSerializer`
`cart_serializer`	`Spree::Api::V3::CartSerializer`
`order_serializer`	`Spree::Api::V3::OrderSerializer`
`line_item_serializer`	`Spree::Api::V3::LineItemSerializer`
`category_serializer`	`Spree::Api::V3::CategorySerializer`
`customer_serializer`	`Spree::Api::V3::CustomerSerializer`
`address_serializer`	`Spree::Api::V3::AddressSerializer`
`payment_serializer`	`Spree::Api::V3::PaymentSerializer`
`fulfillment_serializer`	`Spree::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:

Feature	How
Pagination	Pagy — `?page=2&limit=25`
Filtering	Ransack — `?q[name_cont]=nike`
Sorting	JSON:API style — `?sort=-name`
Authorization	Ownership scoping — `scope` decides what the caller can see (Admin API controllers add the `scoped_resource` permission gate)
Prefixed IDs	Stripe-style — `brand_k5nR8xLq`

Override these methods to customize:

Method	Purpose
`model_class`	ActiveRecord model (required)
`serializer_class`	Alba serializer (required)
`scope`	Base query — add `.where()` to filter
`find_resource`	Custom ID lookup (slug fallback, etc.)
`permitted_params`	Custom strong params
`collection_includes`	Eager 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), declare the attributes in your controller:

def resource_permitted_attributes
  [:name, :slug, :description, :logo]
end

Entries are params.permit fragments, so collections and nested structures use the shapes you would pass there directly — [:name, { region_ids: [] }].

Declare resource_permitted_attributes, not permitted_attributes. The latter is what appends extension-contributed attributes to your list, so overriding it replaces them.

Adding an Attribute to a Core Resource

To make a new column writable on a Spree model without decorating the controllers that write it, append to the model’s permitted attributes:

config/initializers/spree.rb

Spree::Product.additional_permitted_attributes += [:brand_id]

Standard resource endpoints append these to their own allowlist, so one declaration covers the model’s create and update endpoints. Use +=, never = — assigning replaces what another extension added — and declare only attributes of your own, since redeclaring a key the controller already permits replaces its filter rather than widening it.

For merchant-managed data, prefer Custom Fields, which need no code and are filterable and sortable. This is for extensions that add real database columns.

Two endpoints deliberately ignore this hook because their parameters are authorization data rather than resource data: API keys and invitations.

Consuming Custom Endpoints with the SDK

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

​Customizing JSON Responses

​Adding Custom Attributes

​Adding an Association

​Serializer Dependency Keys

​Adding New Endpoints

​Controller

​Routes

​Permitted Attributes

​Adding an Attribute to a Core Resource

​Consuming Custom Endpoints with the SDK

Customizing JSON Responses

Adding Custom Attributes

Adding an Association

Serializer Dependency Keys

Adding New Endpoints

Controller

Routes

Permitted Attributes

Adding an Attribute to a Core Resource

Consuming Custom Endpoints with the SDK