@spree/docs 0.1.0

package/dist/developer/core-concepts/store-credits-gift-cards.md

@@ -0,0 +1,317 @@
+---
+title: Store Credits & Gift Cards
+description: Stored value mechanisms for refunds, loyalty rewards, and gifting
+---
+
+## Overview
+
+Spree provides two stored value mechanisms that customers can use at checkout:
+
+- **Store Credits** - Value assigned directly to a customer's account by admins (refunds, loyalty rewards, compensation)
+- **Gift Cards** - Value with a redeemable code that can be shared and redeemed by anyone
+
+| Feature | Store Credit | Gift Card |
+|---------|--------------|-----------|
+| Purpose | Refunds, loyalty rewards, compensation | Gifting, promotions, marketing |
+| Requires account | Yes (tied to customer account) | No (guests can use at checkout) |
+| Transferable | No | Yes (code can be shared) |
+| Has code | No | Yes |
+| Created by | Admin | Admin |
+| Assignment | Directly to customer | Applied to order via code |
+| Expiration | Configurable by type | Configurable per card |
+
+## Store Credits
+
+Store Credits are monetary values assigned directly to a customer's account. They are commonly used for:
+
+- Refunds (instead of returning money to original payment method)
+- Loyalty rewards
+- Customer compensation
+- Promotional credits
+
+### Store Credit Model
+
+```mermaid
+erDiagram
+    StoreCredit ||--o{ StoreCreditEvent : "has many"
+    StoreCredit ||--o{ Payment : "source for"
+    StoreCredit }o--|| User : "belongs to"
+    StoreCredit }o--|| Store : "belongs to"
+    StoreCredit }o--o| StoreCreditCategory : "belongs to"
+    StoreCredit }o--o| StoreCreditType : "belongs to"
+
+    StoreCredit {
+        decimal amount
+        decimal amount_used
+        decimal amount_authorized
+        string currency
+        string memo
+    }
+
+    StoreCreditCategory {
+        string name
+    }
+
+    StoreCreditType {
+        string name
+        integer priority
+    }
+
+    StoreCreditEvent {
+        string action
+        decimal amount
+        string authorization_code
+    }
+```
+
+### Store Credit Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `amount` | Total credit amount | `100.00` |
+| `amount_used` | Amount already spent | `25.00` |
+| `amount_authorized` | Amount currently authorized for pending orders | `0.00` |
+| `currency` | Currency code | `USD` |
+| `memo` | Optional note about the credit | `Refund for order #R123` |
+
+### Store Credit Categories
+
+Categories help organize store credits by their purpose:
+
+| Category | Description |
+|----------|-------------|
+| Default | General purpose store credit |
+| Gift Card | Store credit created from gift card redemption |
+
+> **INFO:** Categories can be configured as non-expiring. By default, the "Gift Card" category is non-expiring.
+
+### Store Credit Types
+
+Types define the priority in which store credits are applied at checkout:
+
+| Type | Description |
+|------|-------------|
+| Expiring | Credits that may expire (applied first) |
+| Non-expiring | Credits that don't expire (applied last) |
+
+### Store Credit Events
+
+Every action on a store credit is recorded as an event for audit purposes:
+
+| Action | Description |
+|--------|-------------|
+| `allocation` | Initial credit was assigned |
+| `authorize` | Credit was authorized for an order |
+| `capture` | Authorized credit was captured |
+| `void` | Authorization was voided |
+| `credit` | Credit was returned (e.g., order canceled) |
+
+### Assigning Store Credits
+
+Store credits are managed in the Admin Panel:
+
+1. Navigate to **Customers** in the Admin Panel
+2. Select a customer
+3. Go to the **Store Credits** tab
+4. Click **Add Store Credit**
+5. Enter the amount, category, and optional memo
+6. Click **Create**
+
+Store credits can also be created via the Admin API.
+
+### Store Credit Events
+
+The store credit system publishes lifecycle events:
+
+| Event | Description |
+|-------|-------------|
+| `store_credit.created` | Store credit was created |
+| `store_credit.updated` | Store credit was updated |
+
+## Gift Cards
+
+Gift Cards are stored value codes created by admins that can be shared and redeemed by customers. When redeemed, they create a Store Credit on the customer's account.
+
+### Gift Card Model
+
+```mermaid
+erDiagram
+    GiftCard }o--|| Store : "belongs to"
+    GiftCard }o--o| User : "belongs to"
+    GiftCard }o--o| GiftCardBatch : "belongs to"
+    GiftCard ||--o{ StoreCredit : "originator for"
+
+    GiftCard {
+        string code
+        string state
+        decimal amount
+        decimal amount_used
+        decimal amount_authorized
+        string currency
+        datetime expires_at
+        datetime redeemed_at
+    }
+
+    GiftCardBatch {
+        string prefix
+        integer codes_count
+        decimal amount
+        string currency
+        datetime expires_at
+    }
+```
+
+### Gift Card Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `code` | Unique redemption code | `abc1234def` |
+| `amount` | Total gift card value | `50.00` |
+| `amount_used` | Amount already redeemed | `0.00` |
+| `state` | Current state | `active` |
+| `currency` | Currency code | `USD` |
+| `expires_at` | Optional expiration date | `2025-12-31` |
+
+### Gift Card States
+
+```mermaid
+stateDiagram-v2
+    [*] --> active: Created
+    active --> partially_redeemed: Partial redemption
+    active --> redeemed: Full redemption
+    active --> canceled: Admin cancels
+    partially_redeemed --> redeemed: Remaining redeemed
+    partially_redeemed --> partially_redeemed: Another partial redemption
+```
+
+| State | Description |
+|-------|-------------|
+| `active` | Available for redemption |
+| `partially_redeemed` | Some value has been redeemed |
+| `redeemed` | Fully redeemed |
+| `canceled` | Canceled by admin |
+
+> **NOTE:** Gift cards can also be `expired` if `expires_at` date has passed and the card hasn't been fully redeemed.
+
+### Gift Card Lifecycle
+
+```mermaid
+flowchart TB
+    A[Admin creates Gift Card] --> B[Code generated]
+    B --> C[Admin shares code with recipient]
+    C --> D[Recipient enters code at checkout]
+    D --> E[Store Credit created for customer]
+    E --> F[Gift Card marked as redeemed]
+    F --> G[Customer uses Store Credit]
+```
+
+### Creating Gift Cards
+
+#### Single Gift Card
+
+1. Navigate to **Gift Cards** in the Admin Panel
+2. Click **Create Gift Card**
+3. Enter the amount and optional expiration date
+4. Click **Create**
+5. Share the generated code with the recipient
+
+Gift cards can also be created via the Admin API.
+
+#### Batch Gift Card Generation
+
+For promotions or bulk distribution, you can create multiple gift cards at once using Gift Card Batches:
+
+1. Navigate to **Gift Cards** in the Admin Panel
+2. Click **Create Batch**
+3. Enter:
+   - **Prefix** - Code prefix for easy identification (e.g., `HOLIDAY`)
+   - **Count** - Number of cards to generate
+   - **Amount** - Value per card
+   - **Expiration** - Optional expiration date
+4. Click **Create**
+
+> **INFO:** Large batches are processed in the background to avoid timeout issues.
+
+### Redeeming Gift Cards
+
+Gift cards can be redeemed by both **registered customers** and **guest visitors** at checkout. This is a key difference from Store Credits, which require a customer account.
+
+> **INFO:** Unlike Store Credits which are tied to a customer account, Gift Cards can be applied directly to an order during checkout - no account required. This makes them ideal for gifting to anyone.
+
+When a gift card is applied to an order:
+- The gift card value is used to pay for the order
+- The gift card is marked as redeemed (or partially redeemed)
+- No Store Credit is created for guest checkouts
+
+Gift cards are applied using the same coupon codes endpoint as promotion codes. The endpoint automatically detects whether the code is a promotion coupon or a gift card.
+
+
+```typescript SDK
+// Apply gift card code to cart (works for guests and registered customers)
+const cart = await client.carts.couponCodes.apply('cart_abc123', 'abc1234def', {
+  spreeToken: '<token>',
+})
+```
+
+```bash cURL
+# Apply gift card to cart (works for guests and registered customers)
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/coupon_codes' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "code": "abc1234def" }'
+```
+
+
+### Gift Card Events
+
+The gift card system publishes lifecycle events:
+
+| Event | Description |
+|-------|-------------|
+| `gift_card.created` | Gift card was created |
+| `gift_card.redeemed` | Gift card was fully redeemed |
+| `gift_card.partially_redeemed` | Gift card was partially redeemed |
+
+## Using at Checkout
+
+Store Credits and Gift Cards work differently at checkout:
+
+- **Store Credits** - Require a customer account; applied from the customer's balance
+- **Gift Cards** - Can be used by anyone (guests included); applied directly to the order via code
+
+### Checkout Flow
+
+```mermaid
+flowchart TB
+    A[Customer proceeds to payment] --> B{Guest or Registered?}
+    B -->|Registered| C{Has Store Credit?}
+    B -->|Guest| D{Has Gift Card code?}
+    C -->|Yes| E[Display available balance]
+    C -->|No| D
+    D -->|Yes| F[Apply Gift Card to order]
+    D -->|No| G[Show payment methods]
+    E --> H{Apply Store Credit?}
+    H -->|Yes| I[Authorize store credit]
+    H -->|No| D
+    F --> J{Covers order total?}
+    I --> J
+    J -->|Yes| K[Complete order]
+    J -->|No| G
+    G --> L[Customer pays remaining balance]
+    L --> K
+```
+
+### Store Credit Priority
+
+When a registered customer has multiple store credits, they are applied in order of priority:
+
+1. **Expiring credits** - Applied first to ensure they're used before expiration
+2. **Non-expiring credits** - Applied after expiring credits
+
+## Related Documentation
+
+- [Payments](/developer/core-concepts/payments) — Payment processing and methods
+- [Orders](/developer/core-concepts/orders) — Order management
+- [Customers](/developer/core-concepts/customers) — Customer management
+- [Events](/developer/core-concepts/events) — Event system and subscribers

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

@@ -0,0 +1,117 @@
+---
+title: Stores
+description: The central model in Spree — every resource is scoped to a store
+---
+
+## Overview
+
+The Store is the central model in Spree. Every resource — products, orders, markets, payment methods, taxonomies — is scoped to a store. Most setups use a single store, but Spree supports [multi-store](/developer/multi-store/quickstart) configurations where each store operates independently with its own catalog, branding, and checkout.
+
+```mermaid
+erDiagram
+    Store ||--o{ Market : "has many"
+    Store ||--o{ Order : "has many"
+    Store }o--o{ Product : "has many"
+    Store }o--o{ PaymentMethod : "has many"
+    Store }o--o{ ShippingMethod : "has many"
+    Store ||--o{ Taxonomy : "has many"
+    Store ||--o{ StockLocation : "has many"
+
+    Store {
+        string name
+        string code
+        string url
+        boolean default
+        string customer_support_email
+    }
+
+    Market {
+        string name
+        string currency
+        string default_locale
+    }
+
+    Product {
+        string name
+        string status
+    }
+
+    Order {
+        string number
+        string state
+    }
+```
+
+## Store Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `name` | Store name, displayed in the browser title and throughout the site |
+| `code` | Unique identifier for the store |
+| `url` | Primary URL of the store |
+| `meta_description` | SEO description |
+| `meta_keywords` | SEO keywords |
+| `seo_title` | Custom SEO title |
+| `customer_support_email` | Email for customer support inquiries |
+| `mail_from_address` | Sender address for transactional emails |
+| `logo_image_url` | URL to the store's logo |
+| `facebook`, `twitter`, `instagram` | Social media links |
+| `payment_methods` | Payment methods available in this store |
+
+## Fetching Store Information
+
+Use the store endpoint to get the current store's configuration — useful for rendering logos, SEO metadata, and footer content:
+
+
+```typescript SDK
+const store = await client.store.get()
+// {
+//   name: "My Store",
+//   url: "https://mystore.com",
+//   logo_image_url: "https://cdn.mystore.com/logo.png",
+//   customer_support_email: "support@mystore.com",
+//   payment_methods: [{ id: "pm_xxx", name: "Stripe", kind: "card" }],
+//   ...
+// }
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/store' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Markets
+
+[Markets](/developer/core-concepts/markets) let you segment your store into geographic regions, each with its own currency, locale, and set of countries. For example, a single store can have:
+
+- **North America** — USD, English, ships to US and Canada
+- **Europe** — EUR, German, ships to DE, FR, AT, NL
+- **United Kingdom** — GBP, English, ships to GB
+
+See the [Markets](/developer/core-concepts/markets) guide for details.
+
+## Store Resources
+
+Each store has its own set of resources. This means products, orders, and promotions in one store are completely separate from another.
+
+| Resource | Relationship |
+|----------|-------------|
+| [**Markets**](/developer/core-concepts/markets) | A store has many markets, each defining a geographic region with its own currency and locale |
+| [**Orders**](/developer/core-concepts/orders) | An order belongs to one store |
+| [**Products**](/developer/core-concepts/products) | A product can be available in multiple stores |
+| [**Payment Methods**](/developer/core-concepts/payments) | A payment method can be available in multiple stores |
+| [**Shipping Methods**](/developer/core-concepts/shipments) | A shipping method can be available in multiple stores |
+| [**Taxonomies**](/developer/core-concepts/products#taxons-and-taxonomies) | A taxonomy belongs to one store |
+| [**Promotions**](/developer/core-concepts/promotions) | A promotion can apply to multiple stores |
+
+## Multi-Store Setup
+
+To run multiple stores from a single Spree installation, see the [Multi-Store guide](/developer/multi-store/quickstart). Each store gets its own domain, branding, catalog, and checkout — while sharing the same admin dashboard and infrastructure.
+
+## Related Documentation
+
+- [Markets](/developer/core-concepts/markets) — Multi-region commerce within a store
+- [Products](/developer/core-concepts/products) — Product catalog
+- [Orders](/developer/core-concepts/orders) — Order management and checkout
+- [Multi-Store](/developer/multi-store/quickstart) — Running multiple stores

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

@@ -0,0 +1,135 @@
+---
+title: Taxes
+description: Tax categories, tax rates, zones, and how Spree calculates taxes at checkout
+---
+
+## Overview
+
+Spree uses Tax Categories and Tax Rates to calculate taxes for orders. Products are assigned to tax categories, and tax rates define the percentage charged within specific geographic [Zones](/developer/core-concepts/addresses#zones).
+
+```mermaid
+erDiagram
+    TaxCategory ||--o{ TaxRate : "has many"
+    TaxCategory ||--o{ Product : "has many"
+    TaxRate }o--|| Zone : "applies in"
+    TaxRate ||--o{ Adjustment : "creates"
+    Zone ||--o{ ZoneMember : "has many"
+
+    TaxCategory {
+        string name
+        boolean is_default
+        string tax_code
+    }
+
+    TaxRate {
+        string name
+        decimal amount
+        boolean included_in_price
+    }
+
+    Zone {
+        string name
+        string kind
+    }
+```
+
+**Key relationships:**
+- **Tax Category** groups products for tax purposes (e.g., "Clothing", "Food", "Digital")
+- **Tax Rate** defines the percentage and rules for a Tax Category within a [Zone](/developer/core-concepts/addresses#zones)
+- **Zone** defines geographic regions (countries or states) where taxes apply
+- **[Adjustments](/developer/core-concepts/adjustments)** are created on orders/line items to apply taxes
+
+## Tax Categories
+
+Tax categories group products by how they're taxed. Common examples:
+
+- **Clothing** — standard tax rate
+- **Food** — reduced or exempt rate
+- **Digital** — different rules per jurisdiction
+
+Each product is assigned a tax category. One category can be set as the default for products that don't have an explicit assignment.
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `name` | Category name | `Clothing` |
+| `is_default` | Whether this is the default category | `true` |
+| `tax_code` | Code from your tax provider (e.g., Stripe, Avalara) | `1257L` |
+
+## Tax Rates
+
+Tax rates define the percentage charged for a specific tax category within a geographic zone.
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `name` | Rate name | `California Sales Tax` |
+| `amount` | Tax percentage as a decimal | `0.08` (8%) |
+| `included_in_price` | Whether tax is included in the displayed price | `false` |
+| `zone` | Geographic region where this rate applies | `US` |
+| `tax_category` | Products this rate applies to | `Clothing` |
+
+## Tax Types
+
+### Sales Tax (tax-exclusive)
+
+Common in the United States. The displayed price does **not** include tax — tax is added at checkout based on the shipping address.
+
+**Example:** A $17.99 item with 5% sales tax:
+- Displayed price: **$17.99**
+- Tax at checkout: **$0.90**
+- Order total: **$18.89**
+
+### Value Added Tax / VAT (tax-inclusive)
+
+Common in Europe and many other countries. The displayed price **already includes** tax. When shipping outside the tax zone, the tax is removed from the price.
+
+**Example:** A £17.99 item with 5% VAT included:
+- Displayed price: **£17.99** (includes £0.86 VAT)
+- If shipped outside VAT zone: price reduces to **£17.13**
+
+> **INFO:** The `tax_inclusive` setting on [Markets](/developer/core-concepts/markets) controls whether prices are displayed with or without tax for each geographic region.
+
+## Default Tax Zone
+
+Spree uses a default tax zone to estimate taxes before the customer enters a shipping address. This is important for stores with tax-inclusive pricing (VAT) — it determines which tax rate is assumed in the displayed price.
+
+If the customer's shipping address is outside the default tax zone, the assumed tax is removed and the correct rate for their zone is applied.
+
+## Tax Calculation at Checkout
+
+During checkout, taxes are calculated based on the shipping address:
+
+1. The customer's shipping address determines their [Zone](/developer/core-concepts/addresses#zones)
+2. Spree finds matching tax rates for that zone and the product's tax category
+3. Tax [Adjustments](/developer/core-concepts/adjustments) are created on line items
+4. The order total is updated
+
+> **NOTE:** For complex tax requirements (interstate US sales, international VAT), consider using automated tax calculation. The [Stripe Tax integration](/integrations/payments/stripe) handles this automatically.
+
+## Managing Taxes
+
+Tax categories and rates are managed in the Admin Panel under **Settings → Taxes**, or via the Admin API.
+
+### Common Configurations
+
+**US store with state-level sales tax:**
+- Create zones for each taxable state
+- Create tax rates per zone (e.g., 8.25% for California, 6.25% for Texas)
+- Set `included_in_price: false`
+
+**EU store with VAT:**
+- Create a zone for EU countries
+- Create tax rates per country (e.g., 19% Germany, 20% France)
+- Set `included_in_price: true`
+- Set the EU zone as the default tax zone
+
+**Digital products in the EU:**
+- Create a "Digital" tax category
+- Add tax rates for each EU country using the customer's country VAT rate
+- Physical products use the seller's country VAT rate
+
+## Related Documentation
+
+- [Markets](/developer/core-concepts/markets) — Tax-inclusive pricing per market
+- [Addresses](/developer/core-concepts/addresses) — Zones and address-based taxation
+- [Adjustments](/developer/core-concepts/adjustments) — Tax adjustments
+- [Orders](/developer/core-concepts/orders) — How taxes affect order totals

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

@@ -0,0 +1,120 @@
+---
+title: Translations
+description: Translate product content and other resources into multiple languages
+---
+
+## Overview
+
+Spree supports two types of translations:
+
+1. **Resource Translations** — translatable content fields on models like Products, Taxons, and Stores (e.g., product name, description, slug)
+2. **UI Translations** — interface strings used in the admin panel (e.g., button labels, flash messages)
+
+For configuring which locales and currencies are available in your store, see [Markets](/developer/core-concepts/markets). Markets control locale and currency assignment per geographic region.
+
+## Resource Translations
+
+Resources with user-facing content fields have built-in support for translations. Each translatable resource has a corresponding translations table in the database — for example, product translations are stored in `spree_product_translations`.
+
+```mermaid
+erDiagram
+    Product ||--o{ ProductTranslation : "has many"
+    Taxon ||--o{ TaxonTranslation : "has many"
+    Store ||--o{ StoreTranslation : "has many"
+
+    Product {
+        string id PK
+        string status
+    }
+
+    ProductTranslation {
+        string id PK
+        string product_id FK
+        string locale
+        string name
+        text description
+        string slug
+        string meta_title
+        string meta_description
+    }
+
+    TaxonTranslation {
+        string id PK
+        string taxon_id FK
+        string locale
+        string name
+        text description
+        string permalink
+    }
+```
+
+### Translatable Fields
+
+| Resource         | Translatable Fields                                                                                                                                                                 |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Product          | `name`, `description`, `slug`, `meta_description`, `meta_keywords`, `meta_title`                                                                                                             |
+| Taxon            | `name`, `description`, `permalink`                                                                                                                                                        |
+| Taxonomy         | `name`                                                                                                                                                                                |
+| Option Type      | `presentation`                                                                                                                                                                  |
+| Option Value     | `presentation`                                                                                                                                                                  |
+| Property         | `presentation`                                                                                                                                                   |
+| Product Property | `value`                                                                                                                                                                 |
+| Store            | `name`, `meta_description`, `meta_keywords`, `seo_title`, `facebook`, `twitter`, `instagram`, `customer_support_email`, `description`, `address`, `contact_phone` |
+
+### Store API
+
+To retrieve translated content, pass the locale via the `X-Spree-Locale` header or the SDK `locale` option:
+
+
+```typescript SDK
+// Fetch product in French
+const product = await client.products.get('spree-tote', {
+  locale: 'fr',
+})
+
+product.name        // "Sac Spree"
+product.description // "Un sac fourre-tout élégant..."
+product.slug        // "sac-spree"
+
+// List categories in German
+const { data: categories } = await client.categories.list({}, {
+  locale: 'de',
+})
+```
+
+```bash cURL
+# Fetch product in French
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Locale: fr'
+```
+
+
+Slugs are also localized — a product can have different slugs per locale. See [Slugs](/developer/core-concepts/slugs#internationalization) for details.
+
+### Managing Translations
+
+Translations are managed in the Admin Panel. When editing a product, taxon, or other translatable resource, switch the locale selector to enter content in each language.
+
+Translations can also be managed via the Admin API.
+
+## UI Translations
+
+Spree stores UI translation strings in a separate project: [Spree I18n](https://github.com/spree/spree_i18n). This is a community-maintained project with locale files for 43+ languages.
+
+To install UI translations:
+
+```bash
+bundle add spree_i18n
+```
+
+Once installed, all translation files are available automatically — no need to copy any files.
+
+> **INFO:** The full list of supported locales is available in the [Spree I18n GitHub repository](https://github.com/spree-contrib/spree_i18n/tree/main/config/locales).
+
+## Related Documentation
+
+- [Markets](/developer/core-concepts/markets) — Locale and currency configuration per geographic region
+- [Slugs](/developer/core-concepts/slugs) — Localized slugs and URL identifiers
+- [Stores](/developer/core-concepts/stores) — Multi-store setup
+- [Products](/developer/core-concepts/products) — Product translations