@spree/docs 0.1.0

package/dist/developer/core-concepts/pricing.md

@@ -0,0 +1,163 @@
+---
+title: Pricing
+description: Prices, Price Lists, Price Rules, and the Pricing Context — Spree's flexible pricing engine for regional, wholesale, volume, and market-based pricing.
+---
+
+## Overview
+
+Spree's pricing system supports both simple single-currency pricing and advanced multi-currency, rule-based pricing through Price Lists. Every [Variant](/developer/core-concepts/products#variants) can have multiple prices — a base price per currency, plus additional prices from Price Lists that apply conditionally based on rules like geography, customer segment, or quantity.
+
+## Prices
+
+Each variant has one or more `Price` records — one per currency. The API automatically returns the correct price based on the current currency and [Market](/developer/core-concepts/markets) context.
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `amount` | Current selling price | `99.90` |
+| `compare_at_amount` | Original/compare price for strikethrough display | `129.90` |
+| `currency` | ISO 4217 currency code | `USD` |
+
+> **WARNING:** If a product doesn't have a price in the selected currency, it won't appear in Store API responses by default.
+
+### Fetching Prices via API
+
+The Store API returns the resolved price (including Price List rules) for the current currency and market context:
+
+
+```typescript SDK
+// Product price is included by default
+const product = await client.products.get('spree-tote')
+console.log(product.price)          // "15.99" — resolved for current currency
+console.log(product.original_price) // "19.99" — compare-at price (if set)
+
+// Each variant has its own price
+const detailed = await client.products.get('spree-tote', {
+  expand: ['variants'],
+})
+detailed.variants?.forEach(variant => {
+  console.log(variant.price)          // "15.99"
+  console.log(variant.original_price) // "19.99"
+})
+```
+
+```bash cURL
+# Product price is always in the response
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# With variants
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Price Lists
+
+Price Lists allow you to create different pricing strategies based on various conditions. This enables advanced pricing scenarios like:
+
+- **Market-based pricing** — different prices for different [Markets](/developer/core-concepts/markets) (e.g., North America vs Europe)
+- **Regional pricing** — different prices for different geographic zones
+- **Wholesale/B2B pricing** — special prices for business customers
+- **Volume discounts** — tiered pricing based on quantity purchased
+- **Promotional pricing** — time-limited special offers
+- **VIP customer pricing** — exclusive prices for specific customers
+
+### How Price Lists Work
+
+When a customer views a product, Spree's pricing resolver determines which price to use:
+
+1. **Price List priority** — Price Lists are ordered by position; higher priority lists are checked first
+2. **Status** — only `active` or `scheduled` Price Lists are considered
+3. **Date range** — the current time must fall within `starts_at` and `ends_at` (if set)
+4. **Price Rules** — all configured rules must match (or any, depending on `match_policy`)
+
+If no applicable Price List is found, the base price is used.
+
+### Price List Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `name` | Human-readable name for the Price List |
+| `status` | `draft`, `active`, `scheduled`, or `inactive` |
+| `starts_at` | Optional start date when the Price List becomes applicable |
+| `ends_at` | Optional end date when the Price List stops being applicable |
+| `match_policy` | How rules are evaluated: `all` (every rule must match) or `any` (at least one) |
+| `position` | Priority order (lower numbers = higher priority) |
+
+## Price Rules
+
+Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:
+
+| Rule | Description | Use Case |
+|------|-------------|----------|
+| **Market Rule** | Matches based on the current [Market](/developer/core-concepts/markets) | Regional pricing across markets |
+| **Zone Rule** | Matches based on the customer's geographic zone | Country or state-level pricing |
+| **User Rule** | Matches specific customer accounts | VIP customers, wholesale accounts |
+| **Customer Group Rule** | Matches members of customer groups | Loyalty tiers, membership pricing |
+| **Volume Rule** | Matches based on quantity purchased | Bulk discounts, tiered pricing |
+
+### Market Rule
+
+The recommended approach for regional pricing when using Markets. Applies the Price List when the customer is in one of the specified markets.
+
+**Example:** Price a product at $29.99 in North America and €24.99 in Europe, rather than relying on exchange rate conversion.
+
+### Zone Rule
+
+Applies based on the customer's geographic zone. Useful for regional or country-specific pricing when not using Markets.
+
+### User Rule
+
+Limits the Price List to specific customer accounts. Useful for VIP customers, employee pricing, or wholesale accounts.
+
+### Customer Group Rule
+
+Applies to members of specific customer groups. Useful for wholesale tiers, loyalty programs, or membership-based pricing.
+
+### Volume Rule
+
+Applies based on quantity purchased. Supports `min_quantity` and `max_quantity` to create tiered pricing:
+
+| Tier | Quantity | Price |
+|------|----------|-------|
+| Base | 1–9 | $10.00 |
+| Bulk Tier 1 | 10–49 | $8.50 |
+| Bulk Tier 2 | 50+ | $7.00 |
+
+> **INFO:** Custom Price Rules can be created for specialized pricing logic. See the [Customization Quickstart](/developer/customization/quickstart) for details.
+
+## Pricing Context
+
+When resolving prices, Spree considers the full context of the request:
+
+| Context | Source | Description |
+|---------|--------|-------------|
+| Currency | Market or request header | The currency to price in |
+| Market | Customer's country | The [Market](/developer/core-concepts/markets) for market-based rules |
+| Zone | Customer's address | The geographic zone for zone-based rules |
+| Customer | JWT authentication | The logged-in customer for user-based rules |
+| Quantity | Cart line item | The quantity for volume-based rules |
+| Date | Current time | For time-based Price List scheduling |
+
+The Store API automatically builds this context from the request headers (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
+
+> **INFO:** Price resolution results are cached for 15 minutes. Different context combinations are cached separately.
+
+## Time-Based Pricing
+
+Price Lists support scheduling through `starts_at` and `ends_at` attributes. Scheduled Price Lists automatically become applicable when the current time falls within their date range — no manual activation needed.
+
+**Example:** A Black Friday sale Price List with `starts_at: 2025-11-28 00:00` and `ends_at: 2025-11-28 23:59` will automatically activate and deactivate.
+
+## Managing Price Lists
+
+Price Lists are managed in the Admin Panel under **Products → Price Lists**, or via the Admin API.
+
+Each Price List contains prices for specific variants and currencies. Products can be added to a Price List, and individual variant prices set within it.
+
+## Related Documentation
+
+- [Products](/developer/core-concepts/products) — Products, Variants, and base prices
+- [Markets](/developer/core-concepts/markets) — Geographic regions with currency and locale
+- [Taxes](/developer/core-concepts/taxes) — Tax categories, tax rates, and zones
+- [Promotions](/developer/core-concepts/promotions) — Discount-based pricing via promotion rules

package/dist/developer/core-concepts/products.md

@@ -0,0 +1,360 @@
+---
+title: Products
+description: Products, variants, option types, images, prices, and categories
+---
+
+## Overview
+
+A product represents something you sell. Each product has one or more **variants** — the actual purchasable items with their own SKU, price, and inventory. For example, a "T-Shirt" product might have variants for each size and color combination.
+
+Products are organized into **categories** — a flexible hierarchy for grouping products. Categories can be filtered, sorted, and searched via the Store API.
+
+> **INFO:** Product names, descriptions, slugs, and SEO fields are [translatable](/developer/core-concepts/translations#resource-translations).
+
+```mermaid
+erDiagram
+    Product ||--o{ Variant : "has many"
+    Product }o--o{ OptionType : "has many"
+    Product ||--o{ Classification : "has many"
+    Variant ||--o{ Price : "has many"
+    Variant ||--o{ StockItem : "has many"
+    Variant ||--o{ Image : "has many"
+    Variant }o--o{ OptionValue : "has many"
+    OptionType ||--o{ OptionValue : "has many"
+    Taxon ||--o{ Classification : "has many"
+    Taxonomy ||--o{ Taxon : "has many"
+
+    Product {
+        string name
+        string slug
+        string status
+        text description
+        datetime available_on
+    }
+
+    Variant {
+        string sku
+        boolean is_master
+        decimal weight
+    }
+
+    Price {
+        decimal amount
+        decimal compare_at_amount
+        string currency
+    }
+
+    OptionType {
+        string name
+        string presentation
+    }
+
+    OptionValue {
+        string name
+        string presentation
+    }
+```
+
+## Product Attributes
+
+| Attribute | Description | Translatable |
+|-----------|-------------|:---:|
+| `name` | Product name | Yes |
+| `description` | Full product description | Yes |
+| `slug` | URL-friendly identifier (e.g., `spree-tote`) | Yes |
+| `status` | `draft`, `active`, or `archived` | No |
+| `available_on` | Date the product becomes available for sale | No |
+| `discontinue_on` | Date the product is no longer available | No |
+| `meta_title` | Custom SEO title | Yes |
+| `meta_description` | SEO description | Yes |
+| `meta_keywords` | SEO keywords | Yes |
+| `purchasable` | Whether the product can be added to cart | No |
+| `in_stock` | Whether any variant has stock available | No |
+| `price` | Default variant's price in the current currency | No |
+| `thumbnail_url` | URL to the product's first image — always returned, no expand needed | No |
+| `tags` | Array of tag strings for filtering | No |
+
+## Listing Products
+
+
+```typescript SDK
+// List products with pagination
+const { data: products, meta } = await client.products.list({
+  limit: 12,
+  page: 1,
+})
+
+// Filter by price range and availability
+const filtered = await client.products.list({
+  price_gte: 10,
+  price_lte: 50,
+  in_stock: true,
+})
+
+// Search by keyword
+const results = await client.products.list({
+  search: 'tote bag',
+})
+
+// Sort products
+const sorted = await client.products.list({
+  sort: 'price_high_to_low',  // or: price_low_to_high, newest, name_a_z, name_z_a
+})
+```
+
+```bash cURL
+# List products
+curl 'https://api.mystore.com/api/v3/store/products?limit=12&page=1' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Filter by price and stock
+curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=10&q[price_lte]=50&q[in_stock]=true' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Search
+curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+See [Querying](/api-reference/store-api/querying) for the full list of filtering, sorting, and pagination options.
+
+## Getting a Product
+
+
+```typescript SDK
+// Get by slug
+const product = await client.products.get('spree-tote')
+
+// Get with included relations
+const detailed = await client.products.get('spree-tote', {
+  expand: ['variants', 'media', 'option_types', 'categories'],
+})
+// detailed.variants => [{ id: "var_xxx", sku: "TOTE-S-R", price: { amount: "15.99", currency: "USD" }, ... }]
+// detailed.media => [{ id: "img_xxx", url: "https://cdn...", position: 1 }]
+// detailed.option_types => [{ name: "size", presentation: "Size", option_values: [...] }]
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,media,option_types,categories' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Product Filters
+
+Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts:
+
+
+```typescript SDK
+const filters = await client.products.filters()
+// {
+//   option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
+//   price_range: { min: 9.99, max: 199.99 },
+//   categories: [{ id: "ctg_xxx", name: "Clothing", count: 45 }],
+// }
+
+// Scoped to a specific category
+const categoryFilters = await client.products.filters({
+  category_id: 'ctg_xxx',
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/filters' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Scoped to a category
+curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Variants
+
+Variants are the purchasable units of a product. Each variant has its own SKU, price, inventory, and images, and is defined by a unique combination of option values.
+
+| Attribute | Description |
+|-----------|-------------|
+| `sku` | Unique stock keeping unit |
+| `barcode` | Barcode (UPC, EAN, etc.) |
+| `price` | Price in the current currency |
+| `original_price` | Compare-at price for showing discounts |
+| `weight`, `height`, `width`, `depth` | Dimensions for shipping calculations |
+| `in_stock` | Whether stock is available |
+| `backorderable` | Whether the variant can be ordered when out of stock |
+| `option_values` | The option values that define this variant (e.g., Size: Small, Color: Red) |
+
+### Master Variant
+
+Every product has a **master variant** that holds default pricing and inventory. If a product has no option types (e.g., a book with no size/color), the master variant is the only purchasable variant.
+
+### Regular Variants
+
+When a product has option types, each unique combination of option values creates a variant. For example, a T-shirt with sizes (S, M, L) and colors (Red, Green) has 6 variants:
+
+| SKU | Size | Color |
+|-----|------|-------|
+| `TEE-S-R` | Small | Red |
+| `TEE-S-G` | Small | Green |
+| `TEE-M-R` | Medium | Red |
+| `TEE-M-G` | Medium | Green |
+| `TEE-L-R` | Large | Red |
+| `TEE-L-G` | Large | Green |
+
+The product's `default_variant_id` points to the first non-master variant (or the master variant if none exist).
+
+## Option Types and Option Values
+
+Option types define the axes of variation for a product (e.g., Size, Color, Material). Option values are the specific choices within each type (e.g., Small, Medium, Large).
+
+A product must have at least one option type to have multiple variants. Option types and their values are included in the product response when requested:
+
+
+```typescript SDK
+const product = await client.products.get('spree-tee', {
+  expand: ['option_types'],
+})
+
+product.option_types?.forEach(optionType => {
+  console.log(optionType.presentation) // "Size"
+  optionType.option_values.forEach(value => {
+    console.log(value.presentation)    // "Small", "Medium", "Large"
+  })
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+> **INFO:** Option type `name` and `presentation` fields are translatable.
+
+## Media
+
+Media can be attached to the product (via the master variant) or to individual variants. When displaying a product, show the images for the selected variant, falling back to the product-level images.
+
+### Thumbnails
+
+Every product response includes a `thumbnail_url` field — the URL to the first image, ready to use without any expands. Similarly, each variant includes a `thumbnail_url` URL and an `media_count` counter.
+
+Use these fields for product listing pages to avoid loading all images:
+
+
+```typescript SDK
+// List products — thumbnail_url is always included
+const { data: products } = await client.products.list({ limit: 12 })
+
+products.forEach(product => {
+  product.thumbnail_url // "https://cdn.../tote-front.jpg" — no expand needed
+})
+```
+
+```bash cURL
+# thumbnail_url is always in the response — no ?expand needed
+curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+> **WARNING:** Avoid using `?expand=media` on listing pages. This loads **all** images for every product in the response, which is unnecessary when you only need a thumbnail. Use `thumbnail_url` instead and only expand full media on the product detail page.
+
+### All Images
+
+On the product detail page, expand `media` and `variants` to get the full set of images. Images are ordered by `position`:
+
+
+```typescript SDK
+const product = await client.products.get('spree-tote', {
+  expand: ['media', 'variants'],
+})
+
+// Product-level images (from master variant)
+product.media // [{ url: "https://cdn.../tote-front.jpg", position: 1 }, ...]
+
+// Each variant has its own thumbnail and media_count
+product.variants?.forEach(variant => {
+  variant.thumbnail    // "https://cdn.../tote-red.jpg" — always available
+  variant.media_count  // 3 — quick check without loading media
+  variant.media        // full image array (only when ?expand=media)
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+| Field | Available on | Always returned | Description |
+|-------|-------------|:---:|-------------|
+| `thumbnail_url` | Product | Yes | URL to the product's first media |
+| `thumbnail_url` | Variant | Yes | URL to the variant's first media |
+| `media_count` | Variant | Yes | Number of media |
+| `media` | Product, Variant | No | Full image array (requires `?expand=media`) |
+
+## Prices
+
+Each variant can have multiple prices — one per currency, plus additional prices from [Price Lists](/developer/core-concepts/pricing) that apply conditionally based on market, geography, customer segment, or quantity.
+
+The API automatically returns the correct price based on the current currency and market context:
+
+| Field | Description |
+|-------|-------------|
+| `price` | Current selling price |
+| `original_price` | Compare-at price (for showing strikethrough discounts) |
+
+See the [Pricing](/developer/core-concepts/pricing) guide for details on Price Lists, Price Rules, and market-specific pricing.
+
+## Categories
+
+Categories provide a flexible way to organize products into hierarchical trees. Internally, Spree uses Taxonomies (category trees) and Taxons (nodes within those trees), but the Store API exposes them simply as **Categories**.
+
+For example:
+- **Categories** → Clothing → T-Shirts, Dresses
+- **Brands** → Nike, Adidas, Puma
+- **Collections** → Summer 2025, Best Sellers
+
+Products can belong to multiple categories.
+
+
+```typescript SDK
+// List categories
+const { data: categories } = await client.categories.list()
+
+// Get a category by permalink
+const category = await client.categories.get('clothing/shirts')
+
+// List products in a category
+const { data: products } = await client.categories.products.list('clothing/shirts', {
+  limit: 12,
+})
+```
+
+```bash cURL
+# List categories
+curl 'https://api.mystore.com/api/v3/store/categories' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Get a category by permalink
+curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# List products in a category
+curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+> **INFO:** Category `name` and `description` fields are translatable.
+
+## Related Documentation
+
+- [Pricing](/developer/core-concepts/pricing) — Price Lists, Price Rules, and market-specific pricing
+- [Inventory](/developer/core-concepts/inventory) — Stock management and backorders
+- [Media](/developer/core-concepts/media) — Image management
+- [Translations](/developer/core-concepts/translations) — Translating product content
+- [Search & Filtering](/developer/core-concepts/search-filtering) — Full-text search and Ransack filtering
+- [Querying](/api-reference/store-api/querying) — API filtering, sorting, and pagination