Community

Github

Spree Commerce documentation

Developer Guides

Ecommerce API

User Guides

Get started

Support

Returns the details of a specific country.

Retrieve a Country

Countries within Spree are used as a container for states. Countries can be zone members, and also link to an address. The difference between one country and another on an address record can determine which tax rates and shipping methods are used for the order.[Read more about Countries in Spree](/developer/core-concepts/addresses#countries)

Country

Country Includes

States within Spree are used to scope address data slightly more than country. States are useful for tax purposes, as different states in a country may impose different tax rates on different products. In addition to this, different states may cause different tax rates and shipping methods to be used for an order, similar to how countries affect it also.

State

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

Quickstart

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

Adding to an existing Rails app

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

Learn how to use a custom authentication setup with Spree

Authentication

Images

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

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

3rd Party Extensions

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

Creating an Extension

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

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

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

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

Delete a Wishlist

Updates the specific Wishlist by setting the values passed in the request body. Any parameters not provided will be left unchanged.

Update a Wishlist

Returns the default wishlist for the current user, in the current store. If the user does not have a default wishlist in the current store one will be created.

Retrieve the default Wishlist

The Add Item to Wishlist endpoint adds a variant to an existing wishlist by creating a new `wished_item`. A wished item in a wishlist is comparable to a line item in a cart.

Each wished item references a single variant, holds the desired quantity and returns price information determined by the variant price in current currency, and desired quantity.

Add Item to Wishlist

This endpoint sets the wished item quantity.

Set Wished Item Quantity

Delete Item from Wishlist

This endpoint allows you to download a digital item using the unique digital_link token.

The digital_link token value can be found by including `line_items.digital_links` in a completed order lookup.

Use the **Retrieve an Order Status** endpoint found under the Order Status tab, or the **Retrieve an Order** endpoint found under the Account / Orders tab to perform a completed order lookup.

Depending on the store that the item was purchased in, downloads may be restricted to a set number of days since the purchase was made. Additionally, the number of times a download link can be used may be restricted.

If you are not authorized to perform the download due to the download limit restrictions mentioned above, a 403 response will be returned.

API basics

Storefront API

Platform API

Retrieve a Country

Path Parameters

Query Parameters

Response