### Build and Start Production Server

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

Build the Next.js application for production and start the server. Refer to the deployment guide for hosting options.

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

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

### Self-Hosted Node.js Build and Start Commands

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

Install dependencies, build the application, and start the production server for self-hosted Node.js environments.

```bash
npm ci
npm run build

npm start
```

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

### Install Dependencies and Start Packages in Watch Mode

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

After starting the backend, install all TypeScript package dependencies and start them in watch mode for development.

```bash
pnpm install
pnpm dev
```

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

### Admin API SDK Quick Start

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

Demonstrates how to install and use the `@spree/admin-sdk` to interact with the Spree Admin API. It shows client creation with a base URL and secret key, and an example of listing orders with filtering and pagination.

```APIDOC
## Admin API SDK Quick Start

### Description
This snippet shows how to install and initialize the `@spree/admin-sdk` to interact with the Spree Admin API. It includes an example of fetching a list of orders with specific filters.

### Installation
```bash
npm install @spree/admin-sdk
# or
yarn add @spree/admin-sdk
# or
pnpm add @spree/admin-sdk
```

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

const client = createAdminClient({
  baseUrl: 'http://localhost:3000',
  secretKey: 'sk_xxx',
})

const { data: orders } = await client.orders.list({
  status_eq: 'complete',
  limit: 25,
})

console.log(orders)
```

### Parameters
*   `baseUrl` (string): The base URL of your Spree application.
*   `secretKey` (string): Your Spree Admin API secret key.
*   `client.orders.list` parameters:
    *   `status_eq` (string): Filter orders by status (e.g., 'complete').
    *   `limit` (number): The maximum number of orders to return.
```

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

### Get Payment Setup Session

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

Initiates a payment setup session, returning necessary details for client-side integration.

```APIDOC
## POST /api/v2/store/payment_setup_sessions

### Description
Initiates a payment setup session, returning necessary details for client-side integration.

### Method
POST

### Endpoint
/api/v2/store/payment_setup_sessions

### Parameters
#### Request Body
- **payment_method_id** (string) - Required - The ID of the payment method to use.
- **customer_id** (string) - Optional - The ID of the customer initiating the session.
- **order_id** (string) - Optional - The ID of the order associated with the session.
- **return_url** (string) - Optional - The URL to redirect to after payment setup.
- **payment_source_id** (string) - Optional - The ID of an existing payment source.
- **payment_source_type** (string) - Optional - The type of an existing payment source.

### Request Example
```json
{
  "payment_method_id": "pm_12345",
  "customer_id": "cus_abcde",
  "order_id": "ord_67890",
  "return_url": "https://example.com/return"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the payment setup session.
- **status** (string) - The current status of the session (e.g., 'pending', 'completed').
- **external_id** (string) - An external identifier for the payment provider.
- **external_client_secret** (string) - A client secret for integrating with the external payment provider.
- **external_data** (object) - Additional data from the external payment provider.
- **payment_method_id** (string) - The ID of the payment method.
- **payment_source_id** (string) - The ID of the payment source.
- **payment_source_type** (string) - The type of the payment source.
- **customer_id** (string) - The ID of the customer.
- **payment_method** (object) - Details about the payment method.
  - **id** (string)
  - **name** (string)
  - **description** (string)
  - **type** (string)
  - **session_required** (boolean)
  - **source_required** (boolean)

#### Response Example
```json
{
  "id": "pss_xyz789",
  "status": "pending",
  "external_id": "ext_pay_112233",
  "external_client_secret": "cs_test_secret_abc123",
  "external_data": {},
  "payment_method_id": "pm_12345",
  "payment_source_id": null,
  "payment_source_type": null,
  "customer_id": "cus_abcde",
  "payment_method": {
    "id": "pm_12345",
    "name": "Credit Card",
    "description": "Pay with credit card",
    "type": "credit_card",
    "session_required": true,
    "source_required": false
  }
}
```

### Error Handling
#### Error Response (400, 404, 500)
- **error** (object)
  - **code** (string) - Error code (e.g., 'record_not_found', 'validation_error').
  - **message** (string) - Error message.
  - **details** (object, optional) - Field-specific validation errors.

#### Error Response Example
```json
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "payment_method_id": ["is required"]
    }
  }
}
```
```

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

### Configure and Run Spree Development Server

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

Navigates to the server directory, sets up system dependencies (Postgres, Redis, Meilisearch) via `brew` or `apt-get`, installs gems, and prepares the database. Then, starts the Rails server, Sidekiq, and CSS watchers.

```bash
cd server
# Edit .env if needed (e.g. DATABASE_USERNAME, DATABASE_HOST, DATABASE_PORT)
bin/setup        # installs Ruby (via mise), Postgres/Redis/Meilisearch (via brew), gems, prepares database
bin/dev          # starts Rails + Sidekiq + CSS watchers via overmind
```

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

### Initialize Spree Project

Source: https://spreecommerce.org/docs/developer/cli/quickstart

Perform first-run setup for a Spree project, including starting Docker services and seeding the database.

```bash
spree init
```

```bash
spree init --no-sample-data   # Skip sample data
```

```bash
spree init --no-open           # Skip opening browser
```

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

### Start Cloudflare Tunnel

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

Use this command to set up a Cloudflare Tunnel for local webhook testing. Ensure Cloudflared is installed.

```bash
brew install cloudflared
cloudflared tunnel --url http://localhost:3001
```

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

### Vercel CLI Installation and Usage

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

Install the Vercel CLI globally and initiate a deployment.

```bash
npm i -g vercel
vercel
```

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

### Install @spree/storefront-api-v2-sdk (v2 - deprecated)

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

Install the deprecated v2 SDK using npm.

```bash
npm install @spree/storefront-api-v2-sdk
```

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

### Install Adyen Gem and Generator

Source: https://spreecommerce.org/docs/integrations/payments/adyen

Install the Adyen gem and run the generator to set up the integration. Ensure to restart the server after installation.

```bash
bundle add spree_adyen --github spree/spree_adyen && bundle exec rails g spree_adyen:install
```

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

### Start Development Server

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

Run the development server to start building your storefront. Access it via http://localhost:3001.

```bash
npm run dev
```

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

### Copy Environment File

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

Copy the example environment file to create your local configuration file.

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

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

### Get Payment Setup Session

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

Returns a payment setup session with its current status and provider data.

```APIDOC
## Get payment setup session

### Description
Returns a payment setup session with its current status and provider data.

### Method
GET

### Endpoint
/api/v1/payment_setup_sessions/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the payment setup session to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the payment setup session.
- **status** (string) - The current status of the payment setup session (e.g., 'pending', 'completed', 'failed').
- **provider_data** (object) - An object containing data specific to the payment provider.

#### Response Example
```json
{
  "id": "pss_12345abcde",
  "status": "pending",
  "provider_data": {
    "client_secret": "pi_3Kz7f4LkJZ8f4f4f4f4f4f4f_secret_...
  }
}
```
```

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

### Get Payment Setup Session

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

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

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

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

### Create Fixture File for Attachments

Source: https://spreecommerce.org/docs/developer/tutorial/testing

Set up the fixtures directory and create a placeholder image file for testing file attachments.

```bash
mkdir -p spec/fixtures/files && printf '\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05\x18\xd8N\x00\x00\x00\x00IEND\xaeB`\x82' > spec/fixtures/files/logo.png
```

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

### API Request Examples for Product Expansion

Source: https://spreecommerce.org/docs/developer/tutorial/store-api

Demonstrates how to fetch product data with and without expanded brand information using the Store API.

```bash
# Without expand — brand_id only
GET /api/v3/store/products/prod_86Rf07xd4z

# With expand — full brand object included
GET /api/v3/store/products/prod_86Rf07xd4z?expand=brand

# Multiple expands
GET /api/v3/store/products/prod_86Rf07xd4z?expand=brand,variants,categories
```

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

### Install Meilisearch on macOS

Source: https://spreecommerce.org/docs/integrations/search/meilisearch

Install Meilisearch using Homebrew on macOS and start the service. It runs locally without an API key for development.

```bash
brew install meilisearch
meilisearch
# Running at http://localhost:7700 — no API key needed for development
```

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

### Create Database and Run Migrations

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

After installing the new gem, create the new database and run migrations using bin/rails db:create db:migrate.

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

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

### Get Payment Setup Session

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

Retrieves a specific payment setup session using its ID. Requires an API key and optionally a JWT bearer token for authenticated customers.

```javascript
import { createClient } from '@spree/sdk'


const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})


const session = await
  client.customer.paymentSetupSessions.get('pss_abc123', {
    token: '<token>',
  })
```

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

### Get Payment Setup Session

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

Fetches a payment setup session using its unique identifier. This includes details like the session status, external IDs, and payment method information.

```APIDOC
## GET /api/v3/store/customers/me/payment_setup_sessions/{id}

### Description
Returns a payment setup session with its current status and provider data.

### Method
GET

### Endpoint
/api/v3/store/customers/me/payment_setup_sessions/{id}

### Parameters
#### Header Parameters
- **x-spree-api-key** (string) - Required - API Key for authentication.
- **Authorization** (string) - Required - JWT Bearer Token for authenticated customers.

#### Path Parameters
- **id** (string) - Required - Payment setup session ID

### Responses
#### Success Response (200)
- **id** (string) - The unique identifier for the payment setup session.
- **status** (string) - The current status of the payment setup session (e.g., 'pending').
- **external_id** (string) - The external ID of the payment setup session, if applicable.
- **external_client_secret** (string) - The external client secret for the payment setup session, if applicable.
- **external_data** (object) - Additional external data related to the payment setup.
- **payment_method_id** (string) - The ID of the associated payment method.
- **payment_source_id** (any) - The ID of the payment source, if applicable.
- **payment_source_type** (any) - The type of the payment source, if applicable.
- **customer_id** (string) - The ID of the customer associated with the session.
- **payment_method** (object) - Details about the payment method.
  - **id** (string)
  - **name** (string)
  - **description** (any)
  - **type** (string)
  - **session_required** (boolean)
  - **source_required** (boolean)

#### Response Example (200)
```json
{
  "id": "pss_UkLWZg9DAJ",
  "status": "pending",
  "external_id": "seti_test_7ac50408dcea6ac09aa04e3d",
  "external_client_secret": "seti_secret_77e80c695165694be5ef56b9",
  "external_data": {
    "client_secret": "secret_123"
  },
  "payment_method_id": "pm_UkLWZg9DAJ",
  "payment_source_id": null,
  "payment_source_type": null,
  "customer_id": "cus_UkLWZg9DAJ",
  "payment_method": {
    "id": "pm_UkLWZg9DAJ",
    "name": "Credit Card",
    "description": null,
    "type": "bogus",
    "session_required": true,
    "source_required": true
  }
}
```

#### Error Response (404)
- **error** (object)
  - **code** (string) - Error code (e.g., 'record_not_found').
  - **message** (string) - Description of the error.

#### Response Example (404)
```json
{
  "error": {
    "code": "record_not_found",
    "message": "Payment setup session not found"
  }
}
```
```

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

### Start Email Development Server

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

Run this command to start a local development server for rendering emails to HTML files.

```bash
npm run email:dev
```

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

### Payment Setup Session Event Payload Example

Source: https://spreecommerce.org/docs/api-reference/webhooks-events

This JSON represents the payload for a payment setup session event, such as creation, update, or deletion. It includes session status, external IDs, and nested payment method details.

```json
{
  "id": "pss_8mXz3wPq",
  "status": "pending",
  "external_id": "seti_abc123",
  "external_client_secret": "seti_abc123_secret_xyz",
  "external_data": {},
  "payment_method_id": "pm_4xLq8nRt",
  "payment_source_id": "cc_5wPq9mXz",
  "payment_source_type": "Spree::CreditCard",
  "customer_id": "usr_k5nR8xLq",
  "payment_method": {
    "id": "pm_4xLq8nRt",
    "..."
  },
  "created_at": "2025-01-15T10:25:00Z",
  "updated_at": "2025-01-15T10:25:00Z"
}
```

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

### Setup Spree Server Application

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

Clones the spree-starter repository into the `server/` directory and configures `SPREE_PATH` to use local Spree gems.

```bash
pnpm server:setup
```

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

### Create an Address (Success Example)

Source: https://spreecommerce.org/docs/api-reference/platform/addresses/create-an-address

This example demonstrates a successful request to create an address. It shows the expected JSON response with the newly created address details.

```json
{
  "data": {
    "id": "5",
    "type": "address",
    "attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "address1": "5 Lovely Street",
      "address2": "Northwest",
      "city": "Herndon",
      "zipcode": "35005",
      "phone": "555-555-0199",
      "state_name": null,
      "alternative_phone": "555-555-0199",
      "company": "Company",
      "created_at": "2022-11-08T19:33:51.471Z",
      "updated_at": "2022-11-08T19:33:51.471Z",
      "deleted_at": null,
      "label": null,
      "public_metadata": {},
      "private_metadata": {}
    },
    "relationships": {
      "country": {
        "data": {
          "id": "4",
          "type": "country"
        }
      },
      "state": {
        "data": {
          "id": "5",
          "type": "state"
        }
      },
      "user": {
        "data": {
          "id": "1",
          "type": "user"
        }
      }
    }
  }
}
```

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

### Create a Stripe Setup Intent

Source: https://spreecommerce.org/docs/api-reference/storefront/stripe/create-a-stripe-setup-intent

Creates a customer in Stripe (if they don't exist), then an Ephemeral Key for the customer, and finally, a Setup Intent for the customer.

```APIDOC
## POST /api/v2/storefront/stripe/setup_intents

### Description
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.

### Method
POST

### Endpoint
/api/v2/storefront/stripe/setup_intents

### Parameters

### Request Body
This endpoint does not require a request body.

### Response
#### Success Response (200)
- **customer_id** (string) - Stripe's customer ID of the authenticated user (or new one if unauthenticated).
- **ephemeral_key_secret** (string) - Secret of the created ephemeral key.
- **setup_intent_client_secret** (string) - Client secret of the created setup intent

#### Response Example
{
  "customer_id": "cus_Q9uqUz6gVQFku2",
  "ephemeral_key_secret": "ek_test_YWNjdF8xTGtSb1lJaFIwZ0llZ0llyG1LbFhsVU9XWHY1SlNyMXRKVzNJb0hyQ2JZam1HY28_007lGgvGaA",
  "setup_intent_client_secret": "seti_1PJb0hIhR0gIegIeZYQQuxpH_secret_Q9uqLuTAvIJQSK1SFS6OaxJMRpe9s7R"
}
```

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

### Conditionally Render Vendor Selector

Source: https://spreecommerce.org/docs/developer/admin/helper-methods

Renders a vendor selector component if the Spree Enterprise Edition is installed. This is specific to multi-vendor setups.

```erb
<% if enterprise_edition? %>
  <%= render 'spree/admin/vendors/selector' %>
<% end %>
```

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

### Get Supported Currencies

Source: https://spreecommerce.org/docs/developer/admin/helper-methods

Retrieves a list of currencies supported by the current store. Example output shows an array of currency codes.

```erb
<%= supported_currencies %> <%# => ["USD", "EUR", "GBP"] %>
```

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

### Create a Stripe Setup Intent

Source: https://spreecommerce.org/docs/llms.txt

First, the customer must be authenticated. Then, create a SetupIntent for the customer. This SetupIntent will be used to save the customer's payment details for future use.

```APIDOC
## POST /api/v1/stripe/setup_intents

### Description
First, the customer must be authenticated. Then, create a SetupIntent for the customer. This SetupIntent will be used to save the customer's payment details for future use.

### Method
POST

### Endpoint
/api/v1/stripe/setup_intents

### Request Body
- **customer_id** (integer) - Required - The ID of the customer for whom to create the SetupIntent.
```

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

### Percent Per Item Calculator Example

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

Demonstrates the calculation for the Percent Per Item calculator. It applies a percentage discount to each matching product's value.

```text
= ($15 x 2 x 10%) + ($10 x 10%)
= ($30 x 10%) + ($10 x 10%)
= $3 + $1
```

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

### Scaffold a New Spree Store

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

Use this command to create a new Spree Commerce project. The CLI will guide you through an interactive setup process.

```bash
npx create-spree-app@latest my-store
```

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

### Create Payment Setup Session

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

Initiates a payment setup session by providing the payment method ID and an authentication token.

```APIDOC
## POST /customer/payment_setup_sessions

### Description
Creates a new payment setup session for a customer. This is typically used to initiate the process of collecting payment details securely.

### Method
POST

### Endpoint
/customer/payment_setup_sessions

### Parameters
#### Request Body
- **payment_method_id** (string) - Required - The ID of the payment method to be used.

#### Headers
- **Authorization** (string) - Required - Bearer token for customer authentication.

### Request Example
```json
{
  "payment_method_id": "pm_abc123"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the payment setup session.
- **status** (string) - The current status of the payment setup session.
- **external_id** (string, nullable) - An external identifier for the session, if applicable.
- **external_client_secret** (string, nullable) - A client secret for interacting with an external payment provider.
- **external_data** (object) - Additional data from the external payment provider.
- **payment_method_id** (string, nullable) - The ID of the payment method associated with this session.
- **payment_source_id** (string, nullable) - The ID of the payment source created during the session.
- **payment_source_type** (string, nullable) - The type of the payment source.
- **customer_id** (string, nullable) - The ID of the customer associated with this session.
- **payment_method** (object) - Details about the payment method.

#### Response Example
```json
{
  "id": "pss_abc123",
  "status": "pending",
  "external_id": "ext_session_xyz",
  "external_client_secret": "cs_test_secret_abc",
  "external_data": {},
  "payment_method_id": "pm_abc123",
  "payment_source_id": null,
  "payment_source_type": null,
  "customer_id": "cus_123",
  "payment_method": {
    "id": "pm_abc123",
    "name": "Credit Card",
    "description": "Pay with Credit Card",
    "type": "credit_card",
    "session_required": true,
    "source_required": true
  }
}
```

#### Error Response (400 Bad Request, 404 Not Found, etc.)
- **error** (object) - Contains error details.
  - **code** (string) - An error code (e.g., `validation_error`, `record_not_found`).
  - **message** (string) - A human-readable error message.
  - **details** (object, nullable) - Field-specific validation errors.

```json
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "payment_method_id": [
        "is required"
      ]
    }
  }
}
```
```

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

### Get Product in Different Locales (cURL)

Source: https://spreecommerce.org/docs/api-reference/store-api/localization

Example using cURL to fetch product data in English and French, demonstrating the use of the 'X-Spree-Locale' header.

```bash
# English
curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
    -H 'X-Spree-Api-Key: pk_xxx' \
    -H 'X-Spree-Locale: en'

# French
curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
    -H 'X-Spree-Api-Key: pk_xxx' \
    -H 'X-Spree-Locale: fr'
```

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

### Run Core Engine Tests

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

Navigate to the core engine directory and install dependencies, then run all tests.

```bash
cd core
bundle install
bundle exec rake test_app
bundle exec rspec
```

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

### Get Product with Currency-Specific Prices (cURL)

Source: https://spreecommerce.org/docs/api-reference/store-api/localization

Example using cURL to fetch product data with prices in USD and EUR, demonstrating the use of the 'X-Spree-Currency' header.

```bash
# USD prices
curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
    -H 'X-Spree-Api-Key: pk_xxx' \
    -H 'X-Spree-Currency: USD'

# EUR prices
curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
    -H 'X-Spree-Api-Key: pk_xxx' \
    -H 'X-Spree-Currency: EUR'
```

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

### ProductPresenter Output Example

Source: https://spreecommerce.org/docs/developer/how-to/custom-search-provider

Illustrates the output format of the `ProductPresenter#call` method, showing how a single product is transformed into multiple documents, each representing a specific market and locale combination.

```ruby
documents = Spree::SearchProvider::ProductPresenter.new(product, store).call
# => [
#   { prefixed_id: "prod_abc_en_USD", product_id: "prod_abc", locale: "en",
#     currency: "USD", name: "Blue Shirt", price: 29.99, ... },
#   { prefixed_id: "prod_abc_de_EUR", product_id: "prod_abc", locale: "de",
#     currency: "EUR", name: "Blaues Hemd", price: 27.50, ... }
# ]
```

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

### Get Allowed File Types for Upload

Source: https://spreecommerce.org/docs/developer/admin/helper-methods

Retrieves a list of file types that are permitted for Active Storage uploads. Example output shows common image types.

```erb
<%= allowed_file_types_for_upload %>
<%# => ["image/png", "image/jpeg", "image/gif", "image/webp"] %>
```

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

### Get Available Country ISO Codes

Source: https://spreecommerce.org/docs/developer/admin/helper-methods

Retrieves ISO codes for countries that are available for checkout in the current store. Example output shows an array of country codes.

```erb
<%= available_countries_iso %> <%# => ["US", "CA", "GB"] %>
```

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

### Product Response with Expansion

Source: https://spreecommerce.org/docs/api-reference/store-api/relations

This is an example of a product response when `expand=variants,media` is used. Related resources like variants and media are embedded in the response.

```json
{
  "id": "prod_86Rf07xd4z",
  "name": "Spree Tote",
  "slug": "spree-tote",
  "price": { "amount": "15.99", "currency": "USD" },
  "created_at": "2025-01-15T10:30:00Z",
  "variants": [
    {
      "id": "variant_k5nR8xLq",
      "sku": "SPR-TOTE-RED",
      "price": { "amount": "15.99", "currency": "USD" },
      "in_stock": true,
      "option_values": [{ "name": "Red", "option_type_name": "Color" }]
    }
  ],
  "media": [
    {
      "id": "asset_9xPq2wLm",
      "position": 1,
      "alt": "Spree Tote",
      "media_type": "image",
      "product_id": "prod_86Rf07xd4z",
      "variant_ids": ["variant_k5nR8xLq"],
      "original_url": "https://cdn.example.com/spree-tote.jpg",
      "small_url": "https://cdn.example.com/spree-tote-small.jpg",
      "medium_url": "https://cdn.example.com/spree-tote-medium.jpg",
      "large_url": "https://cdn.example.com/spree-tote-large.jpg"
    }
  ]
}
```

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

### Registry Methods: Get and Access Table

Source: https://spreecommerce.org/docs/developer/admin/tables

Provides examples for retrieving a table object from the Spree admin registry by its key, and also shows the shorthand access method.

```ruby
# Get a table
Spree.admin.tables.get(:products)

# Shorthand access
Spree.admin.tables.products
```

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

### GitHub Actions CI/CD Workflow

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

A GitHub Actions workflow to automate the deployment of the Spree Storefront on push to the main branch. Includes setup for Node.js, dependency installation, and build steps.

```yaml
name: Deploy Storefront
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run build

      # Add your deployment step here
      # Example for Vercel:
      # - uses: amondnet/vercel-action@v25
      #   with:
      #     vercel-token: ${{ secrets.VERCEL_TOKEN }}
      #     vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
      #     vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
      #     vercel-args: --prod
```

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

### Organizing Multiple Decorators

Source: https://spreecommerce.org/docs/developer/customization/decorators

This example shows how to structure a product decorator to load other focused decorators for better organization.

```ruby
app/models/spree/product_decorator.rb
# Load focused decorators
require_dependency 'spree/product/brand_decorator'
require_dependency 'spree/product/inventory_decorator'
require_dependency 'spree/product/seo_decorator'
```

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

### Install and Run Migrations

Source: https://spreecommerce.org/docs/developer/upgrades/4.8-to-4.9

Execute these commands to install any missing Spree migrations and apply them to your database.

```bash
bin/rake spree:install:migrations && bin/rails db:migrate
```

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

### List Countries and Get Single Country with States (cURL)

Source: https://spreecommerce.org/docs/api-reference/store-api/localization

Examples using cURL to list all countries, countries within a market, and to retrieve a specific country's details including states.

```bash
# All countries
curl 'http://localhost:3000/api/v3/store/countries' \
    -H 'X-Spree-Api-Key: pk_xxx'

# Countries in a specific market
curl 'http://localhost:3000/api/v3/store/markets/mkt_xxx/countries' \
    -H 'X-Spree-Api-Key: pk_xxx'

# Get a country with states
curl 'http://localhost:3000/api/v3/store/countries/US?expand=states' \
    -H 'X-Spree-Api-Key: pk_xxx'
```

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

### Example Product List Response

Source: https://spreecommerce.org/docs/api-reference/storefront/products/list-all-products

A successful response for listing products includes a 'data' array of product objects, 'included' resources, 'meta' information, and 'links' for pagination.

```json
{
  "data": [
    {
      "id": "96",
      "type": "product",
      "attributes": {
        "name": "Bomber Jacket",
        "description": ">-\n                        Dolorem nulla odit nostrum placeat soluta non vitae\n                        praesentium. Neque asperiores quos necessitatibus sint\n                        placeat. Voluptas aliquid atque veniam iste assumenda\n                        blanditiis. Excepturi odit recusandae laboriosam sunt\n                        temporibus corrupti. Tempore necessitatibus recusandae\n                        eligendi occaecati nesciunt sed illum similique.",
        "available_on": "2021-10-02T11:02:29.288Z",
        "slug": "bomber-jacket",
        "meta_description": null,
        "meta_keywords": null,
        "updated_at": "2021-10-02T11:03:14.681Z",
        "sku": "JacketsandCoats_bomberjacket_38.99",
        "purchasable": true,
        "in_stock": true,
        "backorderable": false,
        "available": true,
        "currency": "USD",
        "price": "38.99",
        "display_price": "$38.99",
        "compare_at_price": null,
        "display_compare_at_price": null
      },
      "relationships": {
        "variants": {
          "data": [
            {
              "id": "212",
              "type": "variant"
            }
          ]
        },
        "option_types": {
          "data": [
            {
              "id": "1"
            }
          ]
        }
      }
    }
  ],
  "included": [],
  "meta": {},
  "links": {}
}
```

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

### List Tags OpenAPI Specification

Source: https://spreecommerce.org/docs/api-reference/admin-api/configuration/list-tags

OpenAPI 3.0.3 specification for the GET /api/v3/admin/tags endpoint. This defines the request parameters, authentication, and response formats, including examples for successful retrieval and error cases.

```yaml
openapi: 3.0.3
info:
  title: Admin API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: >
    Spree Admin API v3 - Administrative API for managing products, orders, and
    store settings.


    ## Authentication


    The Admin API requires a secret API key passed in the `x-spree-api-key`
    header.

    Secret API keys can be generated in the Spree admin dashboard.


    ## Response Format


    All responses are JSON. List endpoints return paginated responses with
    `data` and `meta` keys.

    Single resource endpoints return a flat JSON object.


    ## Resource IDs


    Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,

    `variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,

    request bodies, and Ransack filters all accept them directly.


    ## Error Handling


    Errors return a consistent format:

    ```json

    {
      "error": {
        "code": "validation_error",
        "message": "Validation failed",
        "details": { "name": ["can't be blank"] }
      }
    }

    ```
  version: v3
servers:
  - url: http://{defaultHost}
    variables:
      defaultHost:
        default: localhost:3000
security: []
tags:
  - name: Authentication
    description: Admin user authentication
  - name: Product Catalog
    description: Products, variants, and option types
  - name: Orders
    description: >-
      Order management — orders, items, payments, fulfillments, refunds, gift
      cards, store credits
  - name: Customers
    description: Customer management — profiles, addresses, store credits, credit cards
  - name: Configuration
    description: Store configuration — payment methods, tag autocomplete
paths:
  /api/v3/admin/tags:
    get:
      tags:
        - Configuration
      summary: List tags
      description: >-
        Returns tag names for a given taggable type. Used for autocomplete in
        tag inputs on products, orders, and customers.
      parameters:
        - name: x-spree-api-key
          in: header
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
        - name: taggable_type
          in: query
          required: true
          description: Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: Optional case-insensitive substring filter
          schema:
            type: string
      responses:
        '200':
          description: tags found
          content:
            application/json:
              example:
                data:
                  - name: vip
                  - name: wholesale
        '422':
          description: invalid taggable type
          content:
            application/json:
              example:
                error:
                  code: invalid_taggable_type
                  message: >-
                    taggable_type must be one of Spree::Product, Spree::Order,
                    Spree::LegacyUser
      security:
        - api_key: []
          bearer_auth: []
      x-codeSamples:
        - lang: javascript
          label: Spree Admin SDK
          source: |-        
            import { createAdminClient } from '@spree/admin-sdk'

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

            const { data: tags } = await client.tags.list({
              taggable_type: 'Spree::User',
              q: 'vip',
            })
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication

```

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

### List Available Payment Provider Types (OpenAPI)

Source: https://spreecommerce.org/docs/api-reference/admin-api/configuration/list-available-payment-provider-types

This OpenAPI definition describes the GET request to list available payment provider types. It includes request parameters for authentication and example responses.

```yaml
openapi: 3.0.3
info:
  title: Admin API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: >
    Spree Admin API v3 - Administrative API for managing products, orders, and
    store settings.


    ## Authentication


    The Admin API requires a secret API key passed in the `x-spree-api-key`
    header.

    Secret API keys can be generated in the Spree admin dashboard.


    ## Response Format


    All responses are JSON. List endpoints return paginated responses with
    `data` and `meta` keys.

    Single resource endpoints return a flat JSON object.


    ## Resource IDs


    Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,

    `variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,

    request bodies, and Ransack filters all accept them directly.


    ## Error Handling


    Errors return a consistent format:

    ```json

    {
      "error": {
        "code": "validation_error",
        "message": "Validation failed",
        "details": { "name": ["can't be blank"] }
      }
    }

    ```
  version: v3
servers:
  - url: http://{defaultHost}
    variables:
      defaultHost:
        default: localhost:3000
security: []
tags:
  - name: Authentication
    description: Admin user authentication
  - name: Product Catalog
    description: Products, variants, and option types
  - name: Orders
    description: >-
      Order management — orders, items, payments, fulfillments, refunds, gift
      cards, store credits
  - name: Customers
    description: Customer management — profiles, addresses, store credits, credit cards
  - name: Configuration
    description: Store configuration — payment methods, tag autocomplete
paths:
  /api/v3/admin/payment_methods/types:
    get:
      tags:
        - Configuration
      summary: List available payment provider types
      description: >-
        Returns the registered Spree::PaymentMethod subclasses that can be used
        to create new payment methods. Useful for populating a "Provider"
        dropdown in admin UIs.


        **Required scope:** `read_settings` (for API-key authentication).
      parameters:
        - name: x-spree-api-key
          in: header
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: provider types found
          content:
            application/json:
              example:
                data:
                  - type: bogus
                    label: Bogus
                    description: null
                    preference_schema:
                      - key: dummy_key
                        type: string
                        default: PUBLICKEY123
                      - key: dummy_secret_key
                        type: password
                        default: null
                  - type: custom_payment_source_method
                    label: Custom Payment Source Method
                    description: null
                    preference_schema: []
      security:
        - api_key: []
          bearer_auth: []
      x-codeSamples:
        - lang: javascript
          label: Spree Admin SDK
          source: |-        
            import { createAdminClient } from '@spree/admin-sdk'

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

            const { data: types } = await client.paymentMethods.types()
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication

```