Spree Commerce documentation

Start building awesome eCommerce applications with Spree open-source eg. multi-store, multi-vendor, multi-tenant, multi-language, multi-currency. B2B or B2C.

Quickstart

Architecture

Stores

Orders

Users

Products

Inventory

Payments

Taxes

Promotions

Shipments

Addresses

Spree is ready out of the box to make your brand a global one.

Internationalization

Learn how to customize every part of the Spree stack

Spree Customization Quickstart

Learn how to use a custom authentication setup with Spree

Authentication

Learn how to customize the checkout process in Spree.

Checkout Flow

Permissions

Dependencies

Decorators allow you to add behavior to Spree classes in your application.

Decorators

Learn how to customize the routes in Spree

Routes

Images

Deface Overrides

Extensions provide additional features and integrations for your Spree application. Here's a list of the most popular ones.

3rd Party Extensions

Deploy your Spree application to [Render.com](https://render.com) Platform as a Service platform

Render

Learn how to build a Docker image of your Spree application.

Docker

Assets

Learn how to improve performance of your Spree application by using a CDN (Content Delivery Network).

This guide will cover all sorts of topics related to Spree application performance

Learn how to upgrade your Spree application

This guide covers upgrading a Spree 4.8 application to Spree 4.9.

Upgrading to Spree 4.9

This guide covers upgrading a Spree 4 application to Spree 4.8.

Upgrading to Spree 4.8

This guide covers upgrading a 4.6 Spree application to Spree 4.7.

4.6 to 4.7

This guide covers upgrading a 4.5 Spree application to Spree 4.6.

4.5 to 4.6

This guide covers upgrading a 4.4 Spree application to Spree 4.5

4.4 to 4.5

This guide covers upgrading a 4.3 Spree application to Spree 4.4.

4.3 to 4.4

This guide covers upgrading a 4.2 Spree application to Spree 4.3.

4.2 to 4.3

This guide covers upgrading a 4.1 Spree application to Spree 4.2.

4.1 to 4.2

This guide covers upgrading a 4.0 Spree application to Spree 4.1.

4.0 to 4.1

This guide covers upgrading a 3.7 Spree application to Spree 4.0.

3.7 to 4.0

This guide covers upgrading a 3.6 Spree application, to version 3.7.

3.6 to 3.7

This guide covers upgrading a 3.5 Spree application, to a 3.6 application.

3.5 to 3.6

This guide covers upgrading a 3.4 Spree store, to a 3.5 store.

3.4 to 3.5

This guide covers upgrading a 3.3 Spree store, to a 3.4 store.

3.3 to 3.4

This guide covers upgrading a 3.2 Spree store, to a 3.3 store.

3.2 to 3.3

This guide covers upgrading a 3.1 Spree store, to a 3.2 store.

3.1 to 3.2

This guide covers upgrading a 3.0 Spree store, to a 3.1 store

3.0 to 3.1

This guide covers upgrading a 2.3 Spree store, to a 2.4 store.

2.3 to 2.4

This guide covers upgrading a 2.2 Spree store, to a 2.3 store.

2.2 to 2.3

This guide covers upgrading a 2.1 Spree store, to a 2.2 store.

2.1 to 2.2

This guide covers upgrading a 2.0 Spree store, to a 2.1 store.

2.0 to 2.1

This guide covers all the necessary steps to contributing to Spree source code. We're happy you're here!

Developing Spree

Creating an Extension

PCI Compliance

This guide will show you how to add Spree to an existing Ruby on Rails application.

Adding to an existing Rails app

Spree open-source comes with a fully-featured Ecommerce API for headless eCommerce apps.

Ecommerce API

Learn how to authenticate requests to the Storefront API.

Retrieve an Account

Creates a new account. This endpoint requires the [Spree Auth Devise](https://github.com/spree/spree_auth_devise) gem to be installed.

Create an Account

Updates the users account details. This endpoint requires the [Spree Auth Devise](https://github.com/spree/spree_auth_devise) gem to be installed.

Update an Account

Returns a list of addresses for the current user.

List all Addresses

Creates a new address for the current user.

Create an Address

This endpoint removes the specified address for the current user. It uses a soft delete to retain address information for pre-existing orders.

Remove an Address

Updates the specified address for the current user.

Update an Address

Returns a list of credit cards for the current user.

List all Credit Cards

Removes a specified credit card for the current user with a soft delete to retain payment information for any pre-existing orders.

Remove a Credit Card

Returns the current user's default credit card.

Retrieve the default Credit Card

Returns all completed orders placed by the current user in the current store.

List all Orders

Returns a completed order for the current user within the scope of the current store.

Retrieve an Order

Returns completed order information.

This endpoint is useful when fetching orders placed by a guest user, allowing customers without an account to check the status of their order: (shipment/payment/processing) etc.

Pass the cart `token` value as the `X-Spree-Order-Token` for authorization, and the corresponding cart `number` in the URI **{order_number}** to successfully retrieve an order.

Retrieve an Order Status

Retrieve a Cart

Creates a new cart.

**Please be aware**; The `token` value found in the response body is used to authorize all future operations on this cart through the Auth API Key `X-Spree-Order-Token`.

Create a Cart

Deletes a specified cart.

When this endpoint is successfully executed, all shipments are cancelled, payments are voided, then line items, shipments & payments are all deleted.

Delete a Cart

Adds a variant to the current cart by creating a line item. Each line item represents a specified variant and the desired quantity.

Add an Item to Cart

Sets the quantity of a specified line item.

Set Line Item Quantity

Removes a line item from the cart by deleting the line item.

After deleting the line item, the system will re-calculate taxes, promotions, shipments etc.

Remove a Line Item

This endpoint removed all line items from the cart. Inventory that was previously taken by this order will be re-stocked.

Empty the Cart

Returns a list of shipping rates for the current cart. The rates given are only estimates and can vary from the final shipping rates.

List Estimated Shipping Rates

Associates a guest cart with the currently signed in user.

Associate a Cart with a User

Changes the cart currency and recalculates the cart values.

Change Cart Currency

Applies a coupon code to the current cart.

Apply a Coupon Code

Removes a specified coupon code from the current cart.

Remove a Coupon

Removes all coupons that have been applied to the current cart.

Remove all Coupons

The Update Checkout endpoint allows you to manage the typical stages of an e-commerce checkout system.

Update Checkout

Validate an order before placing it. It will respond with an error when:
- cart was changed
- any order item is out of stock
- any order item is discontinued

Validate order payment

Next Checkout Step

Advances the checkout to the furthest checkout step validation allows, up until the **completed** step.

Advance Checkout

Completes the checkout by marking the order as complete.

**Please be aware**; Once a checkout is marked as `complete` it is considered a completed order, the Cart and Checkout endpoints will no longer access a completed order, and a new cart will need to be created.

If you want to access a completed order you will need to use the **Account / Orders** or **Order Status** endpoints.

Complete Checkout

Selects shipping method for Shipment(s).

To generate shipments you first need to fetch shipping rates via

[Get Shipping Rates](https://api.spreecommerce.org/docs/api-v2/b3A6MzE0Mjc2MQ-list-shipping-rates) endpoint

Selects shipping method for shipment(s)

Returns a list of available shipping rates for the checkout.

Shipping rates are grouped against shipments. Each checkout can have multiple shipments. Some products are in stock and will be shipped immediately, while others might be back-ordered and sent later.

List Shipping Rates

Creates new Payment for the current checkout.

You can either create new payment source (eg. a Credit Card) or use an existing (for signed in users only).

Newly created payment source will be associated to the current signed in user.

System will automatically invalidate previous (non-finalized) payments (excluding store credit / gift card payments).

[More details on payment system](/developer/core-concepts/payments)

Create new Payment

Returns a list of available payment methods for this checkout.

List Payment Methods

The Add Store Credit endpoint takes the users existing store credit from their account and adds a set amount of this store credit to the current cart.

In essence, by adding the user's store credit to a cart, the user's store credit is being spent.

Add Store Credit

Removes store credit from the cart if any had previously been applied.

Remove Store Credit

Return a Stripe Payment Intent

Create a Stripe Payment Intent using provided payment method. It creates a Stripe customer if not exists.

Create a Stripe Payment Intent

First, this endpoint creates a customer in Stripe (if it doesn't already exist), then it creates an Ephemeral Key for the customer, and finally, it creates a Setup Intent for the customer.

Create a Stripe Setup Intent

Returns a list of products for the current Store.

List all Products

Returns Product details. You can use product permalink:

```
GET /api/v2/storefront/products/knitted-high-neck-sweater
```

Or Product ID:

```
GET /api/v2/storefront/products/21
```

**Note** API will attempt a permalink lookup before an ID lookup.

Retrieve a Product

Returns a list of Vendors. Only available in [Enterprise Edition](https://spreecommerce.org/pricing)

List all Vendors

Returns the details of a specified Vendor. Only available in [Enterprise Edition](https://spreecommerce.org/pricing)

Retrieve a Vendor

Returns the current Store. [Read more about Stores](/developer/core-concepts/stores)

Return the current Store

Returns a list of Taxons. [Read more about Taxons](/developer/core-concepts/products#taxons-and-taxonomies)

List all Taxons

Returns the details of a specified taxon.

Retrieve a Taxon

List all Countries

Returns the details of a specific country.

Retrieve a Country

Returns the default country for the current store. By default this will be the US.

Get Default Country

Returns a list of all CMS Pages available in the current store.

List all CMS Pages

To return a single CMS Page you can use the CMS Page slug:

```
GET /api/v2/storefront/cms_pages/about-us
```

or CMS Page ID:

```
GET /api/v2/storefront/cms_pages/37
```

**Note:** API will attempt a Slug lookup before an ID lookup.

Retrieve a CMS Page

Returns a list of all menus available in the current store.

List all Menus

Returns the dertails of a specified menu.

Retrieve a  Menu

Returns all wishlists available to the current user, in the current store.

List all Wishlists

Creates a new wishlist for the current user in the current store.

Create a Wishlist

Retrieves a wishlist using the wishlist token.

If the wishlist is publicly viewable, the endpoint will return the requested wishlist regardless of the user. If the wishlist is private, only the wishlist owner can access the wishlist.

Retrieve a Wishlist

This operation deletes the wishlist identified in the URI `token`.

Getting started

Customizing Spree

Use Cases

Deployment

Upgrading

Contributing

Security

Advanced

Navigation