Skip to main content
Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the Spree API docs.

​
Customizing JSON response

Spree uses a library called JSON API serializers to represent data returned by API endpoints. You can easily replace existing Spree serializers with your own thanks to Spree Dependencies. Here’s a list of all serializers that you can override:
KeyValue
storefront_address_serializerSpree::V2::Storefront::AddressSerializer
storefront_cart_serializerSpree::V2::Storefront::CartSerializer
storefront_credit_card_serializerSpree::V2::Storefront::CreditCardSerializer
storefront_country_serializerSpree::V2::Storefront::CountrySerializer
storefront_user_serializerSpree::V2::Storefront::UserSerializer
storefront_shipment_serializerSpree::V2::Storefront::ShipmentSerializer
storefront_taxon_serializerSpree::V2::Storefront::TaxonSerializer
storefront_payment_method_serializerSpree::V2::Storefront::PaymentMethodSerializer
storefront_payment_serializerSpree::V2::Storefront::PaymentSerializer
storefront_product_serializerSpree::V2::Storefront::ProductSerializer
storefront_estimated_shipment_serializerSpree::V2::Storefront::EstimatedShippingRateSerializer
storefront_store_serializerSpree::V2::Storefront::StoreSerializer
storefront_order_serializerSpree::V2::Storefront::OrderSerializer
storefront_variant_serializerSpree::V2::Storefront::VariantSerializer

​
Adding custom attributes

As a rule of thumb it’s recommended to use Properties and OptionTypes/Option Values for custom attributes and not to modify the Spree database schema
Let’s say you want to customize the Storefront API’s Product serializer to include you custom database column my_newcustom_attribute that you’ve added to the spree_products database table. Let’s start with creating a new serializer file: 
mkdir -p app/serializers && touch app/serializers/my_product_serializer.rb
Place the following code in your new serializer file: 
class MyProductSerializer < Spree::V2::Storefront::ProductSerializer
  attribute :my_new_custom_attribute
end
This serializer will inherit from the Spree::V2::Storefront::ProductSerializer serializer, so you don’t need to rewrite the whole serializer.
Now let’s tell Spree to use this new serializer, in config/initializers/spree.rb please set: 
Spree::Api::Dependencies.storefront_product_serializer = 'MyProductSerializer'
Restart the webserver and hit the Products API to notice that the payload now includes your new attribute.

​
Adding a new association

Let’s say you’ve created a new model called Video that belongs to Product (Product has multiple Videos). Let’s create a new serializer app/serializers/video_serializer.rb: 
class VideoSerializer < Spree::Api::V2::BaseSerializer
  set_type: :video
  
  attributes :url
end
Now in your app/serializers/my_product_serializer.rb 
class MyProductSerializer < Spree::V2::Storefront::ProductSerializer
  attribute :my_new_custom_attribute
  
  has_many :videos, serializer: :video
end
Hitting the Products API you will notice that in the relationships key there will be a new key called videos To include Video response in the Product API add ?includes=videos in the API URL, eg. 
GET https://localhost:3000/api/v2/storefront/products?include=videos