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
---
title: Customizing the Spree API
description: Add new Store API endpoints, customize existing JSON responses with serializer decorators, and extend Spree's REST API to fit your storefront needs.
---
Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](/api-reference/admin-api/endpoints).
For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](/developer/tutorial/model-and-api).
## Customizing JSON Responses
Spree uses [Alba](https://github.com/okuramasafumi/alba) serializers to build API v3 responses. You can replace any serializer via [Spree Dependencies](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:
```ruby 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`:
```ruby
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](/developer/tutorial/model-and-api) for the full example).
Create a serializer for the new model:
```ruby 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:
```ruby 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`:
```ruby
Spree::Api::Dependencies.product_serializer = 'MyApp::ProductSerializer'
```
The brand data is available via `?expand=brand`:
```
GET /api/v3/store/products/prod_86Rf07xd4z?expand=brand
```
### Adding a Field from an Extension
Replacing a serializer works for your own application, but the setting holds one replacement. An extension that replaced `admin_product_serializer` would be silently undone by an application that replaces it too. An extension adds read-only fields to a core serializer instead: an **attribute**, written as it is, or an **association**, a related record or a list of them written by the extension's own serializer:
```ruby server/config/initializers/my_extension.rb
Rails.application.config.after_initialize do
Spree.api.extension_fields.attribute(:admin_product_serializer, method: :warranty_text)
Spree.api.extension_fields.association(
:admin_product_serializer,
one: :warranty,
serializer: 'MyExtension::WarrantySerializer',
expand: true
)
Spree.api.extension_fields.association(
:admin_product_serializer,
many: :warranty_claims,
serializer: 'MyExtension::ClaimSerializer',
expand: true
)
end
```
- **The name** is the response key and the record's method that gives the value: `method:` for an attribute, `one:` or `many:` for an association. `one: :warranty` writes `product.warranty` with the given serializer; `many: :warranty_claims` writes each of `product.warranty_claims`. An extension adds such methods to core models with [model extensions](/developer/customization/decorators#adding-to-a-model-without-a-decorator).
- **A simple computed value** needs no method: name the field and pass `value:`, as in `attribute(:admin_product_serializer, :warranty_months, value: ->(product) { ... })`. An association takes `value:` the same way, beside its `one:` or `many:`.
- **Registered by dependency key**, such as `admin_product_serializer`. If the application replaces that serializer with one that inherits from a core serializer, as shown above, the field still renders on the replacement.
- **`expand: true`** shows the field only when the request asks for it with `?expand=warranty`. Without it, the field is always shown. An association's nested expands reach its serializer, so `?expand=warranty.claims` passes `claims` on, the same way `?expand=variants.media` works. Lists apply the same expands to every item.
- **Associations read on lists are batched** when they are Active Record associations, as core ones are. A value computed by `value:` is read for each record.
- **Names are unique per serializer.** Registering a name that the serializer or another extension already uses raises an error at boot.
- **Not in the generated SDK types.** The extension that adds a field declares its TypeScript type.
This is the read side of [adding an attribute to a core resource](#adding-an-attribute-to-a-core-resource), which makes a field writable.
### 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:
```ruby 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](https://github.com/ddnexus/pagy) — `?page=2&limit=25` |
| Filtering | [Ransack](https://github.com/activerecord-hackery/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 (prefer `request_params`) |
| `collection_includes` | Eager loading for `index` |
### Routes
Add routes in your app's `config/routes.rb`:
```ruby
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
```
### Request Parameters
For endpoints that accept writes (create/update), declare what the body takes
with `request_params`, at the top of the controller. Each attribute names its
type, the way a model attribute or a [preference](/developer/customization/model-preferences) does:
```ruby app/controllers/spree/api/v3/admin/brands_controller.rb
request_params :brand do |body|
body.attribute :name, :string, required: true, on: :create
body.attribute :slug, :string
body.attribute :description, :string, description: 'Shown on the brand page.'
body.attribute :region_ids, :array, of: :id
body.attribute :metadata, :hash
end
```
This one declaration is the endpoint's contract: the controller permits exactly
these keys and nesting, and nothing else. Spree's own endpoints publish the same
declarations in the [API reference](/api-reference/introduction), and the SDK request types
(`ProductCreateParams`, `ProductUpdateParams`, …) are generated from it, so the
controller, the reference and the TypeScript types cannot drift apart.
| Type | Sent as |
|------|---------|
| `:string`, `:boolean`, `:integer` | the JSON type of the same name |
| `:decimal` | a canonical decimal string (`"19.99"`) — every amount of money |
| `:number` | a JSON number — weights, dimensions, coordinates |
| `:id` | a prefixed ID (`brand_k5nR8xLq`) |
| `:country`, `:currency` | an ISO 3166-1 alpha-2 or ISO 4217 code, typed `CountryCode` / `CurrencyCode` |
| `:date`, `:datetime` | ISO 8601 strings |
| `:hash` | an object with any keys, such as `metadata` |
| `:object` | an object with declared attributes: a block, or a shared `shape:` |
| `:array` | a list: `of:` a type or a shared shape, or a block for its items |
| `:any` | a scalar, a list or a hash |
| Option | Meaning |
|------|---------|
| `required: true` | Required on create and update; add `on: :create` to require it only when creating |
| `only: :create` | Accepted on one action alone (`:update` for the other) |
| `choices:` | The values it takes; add `open: true` when extensions may add more |
| `nullable: true` | Accepts `null`, usually to clear a value |
| `description:`, `example:`, `format:` | Documentation for the API reference and the SDK types |
| `deprecated: 'Use x. Removed in 6.1.'` | Keeps it working while the reference and the types flag it |
| `permit: false` | Documented, but read by the action itself rather than permitted |
A custom action declares its own body with a name ending in `Params`:
`request_params 'BrandMergeParams', action: :merge do |body| ... end`.
A shape several endpoints accept, such as an address or a price, is a class in
`app/request_schemas`, declared the way a model declares its attributes. A
subclass starts from its parent's attributes:
```ruby app/request_schemas/spree/api/v3/brand_logo_request_schema.rb
module Spree
module Api
module V3
class BrandLogoRequestSchema < Spree::Api::V3::RequestSchema
publishes 'BrandLogoParams'
attribute :signed_id, :string, required: true
attribute :alt, :string
end
end
end
end
```
Endpoints then reference it, `body.attribute :logo, :object, shape: Spree::Api::V3::BrandLogoRequestSchema`,
or take its attributes into their own body with `body.include_attributes Spree::Api::V3::BrandLogoRequestSchema`.
Without `publishes` the class is a set of attributes other declarations
include, not a type of its own.
<Note>
An endpoint that needs logic of its own can still override
`resource_permitted_attributes` with a plain `params.permit` list, but then
its body is neither documented nor typed. Never override
`permitted_attributes`: it is what appends extension-contributed attributes
to your list, so overriding it replaces them.
</Note>
### 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:
```ruby 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.
A product write also carries its media and variants as nested lists, and those
lists take what `Spree::Media` and `Spree::Variant` declare. One line makes a
media column writable both through the media endpoints and as part of a product
save:
```ruby config/initializers/spree.rb
Spree::Media.additional_permitted_attributes += [:photo_credit]
```
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.
<Note>
For merchant-managed data, prefer [Custom Fields](/developer/core-concepts/metafields),
which need no code and are filterable and sortable. This is for extensions
that add real database columns.
</Note>
### Writable by sellers
The Seller API accepts a narrower set of attributes than the Admin API, so the
list above does not apply to it — an attribute you open to operators stays
operator-only. To let sellers write it too, for example from a field on the
seller panel's product page, declare it again on the seller list:
```ruby config/initializers/spree.rb
Spree::Product.additional_seller_permitted_attributes += [:brand_id]
```
The seller product endpoint's nested media and variant lists read the same
seller lists on `Spree::Media` and `Spree::Variant`.
Only declare attributes a seller may safely set on their own records.
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](/developer/tutorial/storefront) for how to call custom endpoints from TypeScript and extend the generated types.