Spree Commerce

https://spreecommerce.org/docs
Admin
Spree Commerce is an open-source, headless e-commerce platform providing REST APIs and admin...
Tokens:3,386,368
Snippets:18,398
Trust Score:9.8
Update:14 hours ago
Show doc for...
Tokens:
Raw
### Production Build and Start

Source: https://spreecommerce.org/docs/v5/developer/storefront/nextjs/quickstart

Build the production bundle and start the server. See the Deployment guide for hosting options.

```bash
npm run build
npm start
```

--------------------------------

### Setup not available error (404)

Source: https://spreecommerce.org/docs/api-reference/admin-api/authentication/complete-first-run-setup

Example 404 error response when the setup token is invalid or setup is no longer available.

```json
{
  "error": {
    "code": "record_not_found",
    "message": "Setup is not available"
  }
}
```

--------------------------------

### Bootstrap the monorepo with pnpm install and server:setup

Source: https://spreecommerce.org/docs/developer/contributing/developing-spree

Run these commands to install workspace dependencies and set up the backend. Requires Docker running locally; no Ruby, Postgres, or Redis on the host. The setup clones spree-starter, builds the dev image, starts the stack, and prepares the database. First run takes ~5-10 minutes and is idempotent.

```bash
pnpm install        # workspace dependencies
pnpm server:setup   # ~5–10 min on first run; idempotent
```

--------------------------------

### 200 response example for GET /api/v2/platform/promotion_rules

Source: https://spreecommerce.org/docs/api-reference/platform/promotion-rules/return-a-list-of-promotion-rules

Example successful response with a list of promotion rules, including metadata and links.

```json
{
  "data": [
    {
      "id": "1",
      "type": "promotion_rule",
      "attributes": {
        "type": null,
        "created_at": "2022-11-08T19:35:00.589Z",
        "updated_at": "2022-11-08T19:35:00.589Z",
        "code": null,
        "preferences": {}
      },
      "relationships": {
        "promotion": {
          "data": {
            "id": "14",
            "type": "promotion"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "promotion_rule",
      "attributes": {
        "type": null,
        "created_at": "2022-11-08T19:35:00.591Z",
        "updated_at": "2022-11-08T19:35:00.591Z",
        "code": null,
        "preferences": {}
      },
      "relationships": {
        "promotion": {
          "data": {
            "id": "14",
            "type": "promotion"
          }
        }
      }
    }
  ],
  "meta": {
    "count": 2,
    "total_count": 2,
    "total_pages": 1
  },
  "links": {
    "self": "http://www.example.com/api/v2/platform/promotion_rules?page=1&per_page=&include=&filter[type_eq]=",
    "next": "http://www.example.com/api/v2/platform/promotion_rules?filter%5Btype_eq%5D=&include=&page=1&per_page=",
    "prev": "http://www.example.com/api/v2/platform/promotion_rules?filter%5Btype_eq%5D=&include=&page=1&per_page=",
    "last": "http://www.example.com/api/v2/platform/promotion_rules?filter%5Btype_eq%5D=&include=&page=1&per_page=",
    "first": "http://www.example.com/api/v2/platform/promotion_rules?filter%5Btype_eq%5D=&include=&page=1&per_page="
  }
}
```

--------------------------------

### 200 response example for GET /api/v2/platform/promotion_actions

Source: https://spreecommerce.org/docs/api-reference/platform/promotion-actions/return-a-list-of-promotion-actions

Example of a successful 200 response with a list of promotion actions, including metadata and links.

```JSON
{
  "data": [
    {
      "id": "5",
      "type": "promotion_action",
      "attributes": {
        "position": null,
        "type": null,
        "deleted_at": null,
        "created_at": "2022-11-08T19:34:55.838Z",
        "updated_at": "2022-11-08T19:34:55.838Z"
      },
      "relationships": {
        "promotion": {
          "data": {
            "id": "5",
            "type": "promotion"
          }
        }
      }
    },
    {
      "id": "6",
      "type": "promotion_action",
      "attributes": {
        "position": null,
        "type": null,
        "deleted_at": null,
        "created_at": "2022-11-08T19:34:55.839Z",
        "updated_at": "2022-11-08T19:34:55.839Z"
      },
      "relationships": {
        "promotion": {
          "data": {
            "id": "5",
            "type": "promotion"
          }
        }
      }
    }
  ],
  "meta": {
    "count": 2,
    "total_count": 2,
    "total_pages": 1
  },
  "links": {
    "self": "http://www.example.com/api/v2/platform/promotion_actions?page=1&per_page=&include=&filter[type_eq]=",
    "next": "http://www.example.com/api/v2/platform/promotion_actions?filter%5Btype_eq%5D=&include=&page=1&per_page=",
    "prev": "http://www.example.com/api/v2/platform/promotion_actions?filter%5Btype_eq%5D=&include=&page=1&per_page=",
    "last": "http://www.example.com/api/v2/platform/promotion_actions?filter%5Btype_eq%5D=&include=&page=1&per_page=",
    "first": "http://www.example.com/api/v2/platform/promotion_actions?filter%5Btype_eq%5D=&include=&page=1&per_page="
  }
}
```

--------------------------------

### Complete setup with JavaScript Admin SDK

Source: https://spreecommerce.org/docs/api-reference/admin-api/authentication/complete-first-run-setup

Use createAdminClient from @spree/admin-sdk to complete the initial setup. The setup token is printed during installation; the refresh token is set as an HttpOnly cookie, so only token and user are returned in the body.

```javascript
import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// The setup token is printed when Spree is installed. The refresh token is
// set as an HttpOnly cookie; only `token` and `user` come back in the body.
const auth = await client.auth.completeSetup({
  setup_token: 'st_9f2c4e7a1b8d',
  email: 'owner@example.com',
  password: 'Secret123!',
  password_confirmation: 'Secret123!',
  first_name: 'Olivia',
  last_name: 'Owner',
  store_name: 'My Store',
  country_code: 'US',
})
```

--------------------------------

### Quick start: create seller client and list products

Source: https://spreecommerce.org/docs/api-reference/seller-api/introduction

Initialize the seller client, log in, set the token and seller, then list products. The baseUrl defaults to localhost for development; replace with your production URL.

```javascript
import { createSellerClient } from '@spree/seller-sdk'

const client = createSellerClient({
  baseUrl: 'http://localhost:3000',
})

// Sign in, then pick which seller to act as
const { token, sellers } = await client.auth.login({
  email: 'seller@example.com',
  password: 'password123',
})

client.setToken(token)
client.setSeller(sellers[0].id)

const { data: products } = await client.products.list({ limit: 25 })
```

--------------------------------

### GET /api/v3/admin/auth/setup

Source: https://spreecommerce.org/docs/api-reference/admin-api/authentication/check-first-run-setup-availability

Reports whether first-run setup is still available — true only while the installation has no admin user. Unauthenticated; the dashboard login page uses it to offer the setup screen.

```APIDOC
## GET /api/v3/admin/auth/setup

### Description
Reports whether first-run setup is still available — true only while the installation has no admin user. Unauthenticated; the dashboard login page uses it to offer the setup screen.

### Method
GET

### Endpoint
/api/v3/admin/auth/setup

### Response
#### Success Response (200)
- **setup_required** (boolean) - True only until the installation has its first admin user.

#### Response Example
{
  "setup_required": true
}
```

--------------------------------

### Per-page Markdown URLs

Source: https://spreecommerce.org/docs/developer/agentic/llm-docs

Append .md to any docs URL to get raw Markdown for that page. Example URLs for quickstart and core-concepts pages.

```text
https://spreecommerce.org/docs/developer/cli/quickstart.md
https://spreecommerce.org/docs/developer/core-concepts/orders.md
```

--------------------------------

### Complete setup with API request

Source: https://spreecommerce.org/docs/api-reference/admin-api/authentication/complete-first-run-setup

Raw API call to POST /auth/setup with the same payload as the JavaScript example. Returns 200 on success, 404 if the setup token is invalid or already used.

```bash
spree api post /auth/setup -d '{"setup_token":"st_9f2c4e7a1b8d","email":"owner@example.com","password":"Secret123!","password_confirmation":"Secret123!","first_name":"Olivia","last_name":"Owner","store_name":"My Store","country_code":"US"}'
```

--------------------------------

### POST /api/v3/admin/auth/setup

Source: https://spreecommerce.org/docs/api-reference/admin-api/authentication/complete-first-run-setup

Completes the first-run setup by creating the admin account and optionally loading sample data. The response returns immediately, while sample data loading continues in the background.

```APIDOC
## POST /api/v3/admin/auth/setup

### Description
Completes the first-run setup by creating the admin account and optionally loading sample data. The response returns immediately, while sample data loading continues in the background.

### Method
POST

### Endpoint
/api/v3/admin/auth/setup

### Parameters
#### Request Body
- **locale** (enum<string>) - Optional - The locale for the admin account. Available options include `en`, `fr`, `de`, etc. Example: `"en"`.
- **currency** (enum<string>) - Optional - ISO 4217 currency. Defaults to the country's own currency; pass one only when the store prices in something else. Available options include `USD`, `EUR`, etc. Example: `"USD"`.
- **sample_data** (boolean) - Optional - Load the demo catalog, customers and orders in the background once the admin account exists. The load takes minutes, so the response does not wait for it.

### Response
#### Success Response (200)
- **application/json** - Setup completed.

#### Response Example
```json
{
  "status": "setup completed"
}
```
```

--------------------------------

### 200 response example for GET seller

Source: https://spreecommerce.org/docs/api-reference/store-api/sellers/get-a-seller

Example of a successful response containing seller profile fields.

```json
{
  "id": "sel_UkLWZg9DAJ",
  "name": "Sparks Audio",
  "slug": "sparks-audio",
  "about": "",
  "about_html": "",
  "logo_url": null,
  "square_logo_url": null,
  "cover_photo_url": null
}
```

--------------------------------

### Successful setup response (200)

Source: https://spreecommerce.org/docs/api-reference/admin-api/authentication/complete-first-run-setup

Example 200 response body containing the authentication token and user details, including roles and store information.

```json
{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjZjMjg1ODk5LTExMzUtNDBhMi1hNDBiLTE4NjNiODcwZDRjYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.Go2eUEiXf7rVD5mwtNMqkWqUGcBfhxk3b7JT8dw8uiE",
  "user": {
    "id": "adm_UkLWZg9DAJ",
    "email": "owner@example.com",
    "first_name": "Olivia",
    "last_name": "Owner",
    "full_name": "Olivia Owner",
    "selected_locale": null,
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z",
    "avatar_url": null,
    "roles": [
      {
        "id": "role_UkLWZg9DAJ",
        "name": "admin"
      }
    ],
    "stores": [
      {
        "id": "store_UkLWZg9DAJ",
        "name": "My Store",
        "code": "spree_1"
      }
    ]
  }
}
```

--------------------------------

### curl example for GET seller

Source: https://spreecommerce.org/docs/api-reference/store-api/sellers/get-a-seller

Uses curl to send a GET request with the API key header.

```curl
curl --request GET \
  --url http://{defaultHost}/api/v3/store/sellers/{id} \
  --header 'x-spree-api-key: <api-key>'
```

--------------------------------

### Copy the environment file

Source: https://spreecommerce.org/docs/developer/storefront/nextjs/quickstart

Copy the example environment file to .env.local to begin configuration.

```bash
cp .env.local.example .env.local
```

--------------------------------

### Install dependencies and build the storefront

Source: https://spreecommerce.org/docs/developer/storefront/nextjs/deployment

Run these commands to install dependencies and build the storefront for production. Uses pnpm with a frozen lockfile.

```bash
pnpm install --frozen-lockfile
pnpm build
```

--------------------------------

### Install extension and run migrations

Source: https://spreecommerce.org/docs/developer/contributing/creating-an-extension

Install the gem and copy the extension's migrations into the application, then run them. After this, the Store API serves reviews at /api/v3/store/reviews and the Admin API manages them at /api/v3/admin/reviews.

```bash
bundle install
bin/rails g spree_reviews:install
```

--------------------------------

### JavaScript fetch example for GET company invitation

Source: https://spreecommerce.org/docs/api-reference/store-api/companies/look-up-an-invitation

Use this JavaScript example to call the GET /api/v3/store/company_invitations/{token} endpoint. It requires an x-spree-api-key header with a publishable API key. The token is a plaintext invitation token from the invite email.

```JavaScript
const options = {method: 'GET', headers: {'x-spree-api-key': '<api-key>'}};

fetch('http://{defaultHost}/api/v3/store/company_invitations/{token}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Get Payment Setup Session - Store SDK

Source: https://spreecommerce.org/docs/developer/core-concepts/payments

Retrieves a payment setup session by its ID. Requires customer authentication.

```javascript
const session = await client.customer.paymentSetupSessions.get('pss_abc123', options)
```

--------------------------------

### POST /api/v3/admin/auth/setup

Source: https://spreecommerce.org/docs/api-reference/admin-api/authentication/complete-first-run-setup

Completes the first-run setup by creating the first admin account and adopting the seeded store. Requires a one-time setup token and returns a JWT access token and user information.

```APIDOC
## POST /api/v3/admin/auth/setup

### Description
Creates the first admin account and adopts the seeded store, authorized by the one-time setup token printed at install time. Issues a JWT access token and a refresh-token cookie exactly like login. Returns 404 once any admin user exists — the flow is closed permanently after setup.

### Method
POST

### Endpoint
/api/v3/admin/auth/setup

### Parameters
#### Request Body
- **setup_token** (string) - Required - The one-time token from the install output.
- **email** (string<email>) - Required - Example: `"owner@example.com"`
- **password** (string) - Required
- **password_confirmation** (string) - Optional
- **first_name** (string) - Optional - Example: `"Olivia"`
- **last_name** (string) - Optional - Example: `"Owner"`
- **store_name** (string) - Optional - Example: `"My Store"`
- **country_code** (enum<string>) - Required - ISO 3166-1 alpha-2 country the store sells from. It determines the default market, the warehouse, the delivery zones and the currency. Available options: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AR`, `AS`, `AT`, `AU`, `AW`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GT`, `GU`, `GW`, `GY`, `HK`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW` - Example: `"US"`
- **locale** (enum<string>) - Optional - Storefront locale. Defaults to the country's own language. Available options: `aa`, `ab`, `ae`, `af`, `ak`, `am`, `an`, `ar`, `as`, `av`, `ay`, `az`, `ba`, `be`, `bg`, `bh`, `bi`, `bm`, `bn`, `bo`, `br`, `bs`, `ca`, `ce`, `ch`, `co`, `cr`, `cs`, `cu`, `cv`, `cy`, `da`, `de`, `de-AT`, `de-CH`, `dv`, `dz`, `ee`, `el`, `en`, `en-AU`, `en-CA`, `en-GB`, `en-IN`, `en-NZ`, `en-US`, `eo`, `es`, `es-419`, `es-CL`, `es-EC`, `es-MX`, `et`

### Request Example
```json
{
  "setup_token": "st_9f2c4e7a1b8d",
  "email": "owner@example.com",
  "password": "Secret123!",
  "password_confirmation": "Secret123!",
  "first_name": "Olivia",
  "last_name": "Owner",
  "store_name": "My Store",
  "country_code": "US"
}
```

### Response
#### Success Response (200)
- **token** (string) - JWT access token.
- **user** (object) - The created admin user object.
  - **id** (string) - User ID.
  - **email** (string) - User email.
  - **first_name** (string) - User first name.
  - **last_name** (string) - User last name.
  - **full_name** (string) - User full name.
  - **selected_locale** (string|null) - Selected locale.
  - **created_at** (string) - Creation timestamp.
  - **updated_at** (string) - Update timestamp.
  - **avatar_url** (string|null) - Avatar URL.
  - **roles** (array) - List of roles.
    - **id** (string) - Role ID.
    - **name** (string) - Role name.
  - **stores** (array) - List of stores.
    - **id** (string) - Store ID.
    - **name** (string) - Store name.
    - **code** (string) - Store code.

#### Response Example
```json
{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjZjMjg1ODk5LTExMzUtNDBhMi1hNDBiLTE4NjNiODcwZDRjYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.Go2eUEiXf7rVD5mwtNMqkWqUGcBfhxk3b7JT8dw8uiE",
  "user": {
    "id": "adm_UkLWZg9DAJ",
    "email": "owner@example.com",
    "first_name": "Olivia",
    "last_name": "Owner",
    "full_name": "Olivia Owner",
    "selected_locale": null,
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z",
    "avatar_url": null,
    "roles": [
      {
        "id": "role_UkLWZg9DAJ",
        "name": "admin"
      }
    ],
    "stores": [
      {
        "id": "store_UkLWZg9DAJ",
        "name": "My Store",
        "code": "spree_1"
      }
    ]
  }
}
```

#### Error Response (404)
- **error** (object) - Error details.
  - **code** (string) - Error code.
  - **message** (string) - Error message.

#### Error Example
```json
{
  "error": {
    "code": "record_not_found",
    "message": "Setup is not available"
  }
}
```

```

--------------------------------

### 200 Response example for GET /api/v2/platform/adjustments/{id}

Source: https://spreecommerce.org/docs/api-reference/platform/adjustments/return-an-adjustment

Example of a successful response (200) containing the adjustment object with attributes and relationships.

```JSON
{
  "data": {
    "id": "6",
    "type": "adjustment",
    "attributes": {
      "source_type": "Spree::TaxRate",
      "adjustable_type": "Spree::LineItem",
      "amount": "1.0",
      "label": "Shipping",
      "mandatory": null,
      "eligible": true,
      "created_at": "2022-11-08T19:33:54.871Z",
      "updated_at": "2022-11-08T19:33:54.875Z",
      "state": "open",
      "included": false,
      "display_amount": "$1.00"
    },
    "relationships": {
      "order": {
        "data": {
          "id": "8",
          "type": "order"
        }
      },
      "adjustable": {
        "data": {
          "id": "2",
          "type": "line_item"
        }
      },
      "source": {
        "data": {
          "id": "5",
          "type": "tax_rate"
        }
      }
    }
  }
}
```

--------------------------------

### Complete the database switch: bundle install, db:create, db:migrate, spree_sample:load

Source: https://spreecommerce.org/docs/developer/deployment/database

After running db:system:change, install the new gem, create the database and run migrations, and optionally load sample data.

```bash
bundle install
```

```bash
bin/rails db:create db:migrate
```

```bash
bin/rails spree_sample:load
```

--------------------------------

### Create Product with Prices

Source: https://spreecommerce.org/docs/api-reference/admin-api/monetary-amounts

Example of creating a product with prices using the Admin SDK and CLI, demonstrating the string format for monetary amounts.

```APIDOC
## Create Product with Prices

### Description
Creates a product with prices, where monetary amounts are sent as decimal strings in canonical format.

### Method
POST

### Endpoint
/products

### Request Body
- **name** (string) - Required - Product name.
- **prices** (array) - Required - List of price objects.
  - **currency** (string) - Required - ISO currency code.
  - **amount** (string) - Required - Price amount as a decimal string (e.g., "29.99").
  - **compare_at_amount** (string) - Optional - Compare-at price as a decimal string.

### Request Example
```json
{
  "name": "Classic Tee",
  "prices": [
    {
      "currency": "USD",
      "amount": "29.99",
      "compare_at_amount": "39.99"
    }
  ]
}
```

### Response
#### Success Response (200)
- Product object with created product details.

#### Error Response (422)
- **error** (object) - Error details.
  - **code** (string) - Error code, e.g., "invalid_money_format".
  - **message** (string) - Error message.
  - **details** (object) - Field-specific error messages.

### Error Example
```json
{
  "error": {
    "code": "invalid_money_format",
    "message": "amount must be a decimal string like \"19.99\"",
    "details": {
      "amount": ["must be a decimal string like \"19.99\""]
    }
  }
}
```

### Notes
- Amounts must be canonical: period decimal separator, no thousands grouping.
- JSON numbers, localized formats, and excessive decimals are rejected.
- A null value clears the amount.
```

--------------------------------

### Install cloudflared via Homebrew

Source: https://spreecommerce.org/docs/developer/storefront/nextjs/wallet-payments

Install the Cloudflare Tunnel client on macOS using Homebrew. Required before starting a tunnel.

```bash
brew install cloudflared
```

--------------------------------

### Run importmap, turbo, and stimulus installers

Source: https://spreecommerce.org/docs/v5/developer/upgrades/4.x-to-4.8

Run these generators to install importmap, turbo, and stimulus as part of the asset management setup.

```bash
bin/rails importmap:install && bin/rails turbo:install && bin/rails stimulus:install
```

--------------------------------

### Start the storefront dev server

Source: https://spreecommerce.org/docs/v5/developer/create-spree-app/quickstart

Run this command in a separate terminal from the project root to start the storefront development server. It assumes you included the storefront during setup. After running, open http://localhost:3001 to see your store.

```bash
cd my-store/apps/storefront
npm run dev
```

--------------------------------

### 200 Response example for GET /api/v2/platform/data_feeds/{id}

Source: https://spreecommerce.org/docs/api-reference/platform/data-feeds/return-a-data-feed

Example of a successful response (200) containing the data feed object with attributes and relationships.

```JSON
{
  "data": {
    "id": "1",
    "type": "data_feed",
    "attributes": {
      "name": "First Data Feed",
      "type": "Spree::DataFeed::Google",
      "slug": "e593ae1f-630a-4f77-832f-0489da1c921b",
      "active": true
    },
    "relationships": {
      "store": {
        "data": {
          "id": "1",
          "type": "store"
        }
      }
    }
  }
}
```

--------------------------------

### Start the development server

Source: https://spreecommerce.org/docs/developer/storefront/nextjs/quickstart

Run pnpm dev to start the development server. Open http://localhost:3001 in your browser.

```bash
pnpm dev
```

--------------------------------

### Run development server for email preview

Source: https://spreecommerce.org/docs/v5/developer/storefront/nextjs/emails

Starts the storefront in development mode to preview emails at http://localhost:3001/dev/emails.

```bash
npm run dev
```

--------------------------------

### Error response (404) for complete payment setup session

Source: https://spreecommerce.org/docs/api-reference/store-api/customers/complete-payment-setup-session

Example of a 404 error response when the payment setup session is not found.

```json
{
  "error": {
    "code": "record_not_found",
    "message": "Payment setup session not found"
  }
}
```

--------------------------------

### cURL example for GET /api/v2/platform/store_credit_types

Source: https://spreecommerce.org/docs/api-reference/platform/store-credit-types/return-a-list-of-store-credit-types

Sends a GET request using cURL to the store credit types endpoint with a Bearer token.

```cURL
curl --request GET \
  --url http://{defaultHost}/api/v2/platform/store_credit_types \
  --header 'Authorization: Bearer <token>'
```

--------------------------------

### POST /customers/me/payment_setup_sessions

Source: https://spreecommerce.org/docs/api-reference/store-api/migrating-from-storefront-api-v2

Creates a payment setup session to save a card for future use.

```APIDOC
## POST /customers/me/payment_setup_sessions

### Description
Creates a payment setup session to save a card for future use.

### Method
POST

### Endpoint
/customers/me/payment_setup_sessions

### Request Body
- **payment_method_id** (string) - Required - The payment method ID.
- **gateway_payload** (object) - Required - Gateway-specific payload.

### Request Example
{
  "payment_method_id": "pm_123",
  "gateway_payload": {}
}

### Response
#### Success Response (200)
- **id** (string) - Setup session ID.
- **status** (string) - Session status.

#### Response Example
{
  "id": "setup_session_123",
  "status": "pending"
}
```

--------------------------------

### cURL example for GET /api/v2/platform/option_types/{id}

Source: https://spreecommerce.org/docs/api-reference/platform/option-types/return-an-option-type

Uses curl to make a GET request with a Bearer token. The response is printed to stdout.

```cURL
curl --request GET \
  --url http://{defaultHost}/api/v2/platform/option_types/{id} \
  --header 'Authorization: Bearer <token>'
```

--------------------------------

### POST /auth/setup

Source: https://spreecommerce.org/docs/api-reference/admin-api/authentication/complete-first-run-setup

Completes the first-run setup of a Spree store. Requires a setup token and owner credentials. Returns an authentication token and user information.

```APIDOC
## POST /auth/setup

### Description
Completes the first-run setup of a Spree store. Requires a setup token and owner credentials. Returns an authentication token and user information.

### Method
POST

### Endpoint
/auth/setup

### Parameters
#### Request Body
- **setup_token** (string) - Required - The setup token printed when Spree is installed.
- **email** (string) - Required - Email address of the store owner.
- **password** (string) - Required - Password for the owner account.
- **password_confirmation** (string) - Required - Confirmation of the password.
- **first_name** (string) - Required - First name of the owner.
- **last_name** (string) - Required - Last name of the owner.
- **store_name** (string) - Required - Name of the store.
- **country_code** (string) - Required - ISO country code for the store.

### Request Example
{
  "setup_token": "st_9f2c4e7a1b8d",
  "email": "owner@example.com",
  "password": "Secret123!",
  "password_confirmation": "Secret123!",
  "first_name": "Olivia",
  "last_name": "Owner",
  "store_name": "My Store",
  "country_code": "US"
}

### Response
#### Success Response (200)
- **token** (string) - Authentication token.
- **user** (object) - User details including id, email, name, roles, and stores.

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjZjMjg1ODk5LTExMzUtNDBhMi1hNDBiLTE4NjNiODcwZDRjYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.Go2eUEiXf7rVD5mwtNMqkWqUGcBfhxk3b7JT8dw8uiE",
  "user": {
    "id": "adm_UkLWZg9DAJ",
    "email": "owner@example.com",
    "first_name": "Olivia",
    "last_name": "Owner",
    "full_name": "Olivia Owner",
    "selected_locale": null,
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z",
    "avatar_url": null,
    "roles": [
      {
        "id": "role_UkLWZg9DAJ",
        "name": "admin"
      }
    ],
    "stores": [
      {
        "id": "store_UkLWZg9DAJ",
        "name": "My Store",
        "code": "spree_1"
      }
    ]
  }
}

#### Error Response (404)
- **error** (object) - Error details with code and message.

#### Error Example
{
  "error": {
    "code": "record_not_found",
    "message": "Setup is not available"
  }
}
```

--------------------------------

### Start the Spree storefront dev server

Source: https://spreecommerce.org/docs/developer/create-spree-app/quickstart

Run this in a separate terminal after setup to start the storefront. It serves the store at http://localhost:3001.

```bash
cd my-store/apps/storefront
pnpm dev
```

--------------------------------

### Example 200 response for GET /api/v2/storefront/store

Source: https://spreecommerce.org/docs/api-reference/storefront/stores/return-the-current-store

Example JSON response returned when the request is successful, showing the store object without includes.

```JSON
{ "data": { "id": "3", "type": "store", "attributes": { "name": "Mystore", "url": "spree-demo.com", "meta\_description": "Luxury clothing store for men and women.", "meta\_keywords": "luxury clothing men women", "seo\_title": "", "default\_currency": "USD", "default": true, "supported\_currencies": "EUR,GBP,USD", "facebook": "https://www.facebook.com/mystorename", "twitter": "https://twitter.com/mystorename", "instagram": "https://instagram.com/mystorename", "default\_locale": "en", "customer\_support\_email": "support@mystore.com", "description": "Mystore has been selling luxury clothing for more than 20 years and has 15 stores currently.", "address": "813 Howard Street, Oswego NY 13126, USA", "contact\_phone": "+123456789", "supported\_locales": "en", "favicon\_path": "/assets/favicon.ico" }, "relationships": { "default\_country": { "data": { "id": "2", "type": "country" } } } } }
```
Tokens:
Raw