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.

13.4 KB
Raw Blame
---
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.