@spree/docs 0.1.0

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

@@ -0,0 +1,187 @@
+---
+title: Metafields
+description: Add custom structured data to products, orders, and other resources with type-safe metafields
+---
+
+## Overview
+
+Metafields provide a flexible, type-safe system for adding custom structured data to Spree resources. Unlike [metadata](/developer/customization/metadata) which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls.
+
+Use metafields for:
+
+- Product specifications (manufacturer, material, dimensions)
+- Custom business logic fields
+- Integration data from external systems
+- Order-specific custom attributes
+
+> **NOTE:** Metafields are available from Spree 5.2 onwards.
+
+## Architecture
+
+```mermaid
+erDiagram
+    MetafieldDefinition ||--o{ Metafield : "defines schema for"
+    Product ||--o{ Metafield : "has many"
+    Variant ||--o{ Metafield : "has many"
+    Order ||--o{ Metafield : "has many"
+
+    MetafieldDefinition {
+        string namespace
+        string key
+        string name
+        string metafield_type
+        string resource_type
+        string display_on
+    }
+
+    Metafield {
+        string type
+        text value
+        string resource_type
+    }
+```
+
+```mermaid
+flowchart LR
+    subgraph Definition
+        A[MetafieldDefinition] --> B["namespace: properties"]
+        A --> C["key: manufacturer"]
+        A --> D["type: ShortText"]
+        A --> E["resource_type: Product"]
+        A --> F["display_on: both"]
+    end
+
+    subgraph Instance
+        G[Metafield] --> H["value: Wilson"]
+        G --> I["resource: Product #1"]
+    end
+
+    A -.->|"defines schema"| G
+```
+
+- **MetafieldDefinition** — the blueprint that defines the data type, target resource, and visibility
+- **Metafield** — stores the actual value for a specific resource instance
+
+## Data Types
+
+| Type | Description | Example Values |
+|------|-------------|----------------|
+| Short Text | Brief text fields | SKU codes, brand names, tags |
+| Long Text | Longer text content | Care instructions, notes |
+| Rich Text | Formatted HTML content | Product descriptions with formatting |
+| Number | Numeric values | Weight, quantity, ratings |
+| Boolean | True/false flags | Is featured, requires signature |
+| JSON | Structured data | Configuration, complex objects |
+
+## Visibility Control
+
+Metafields support three visibility levels via the `display_on` attribute:
+
+| Visibility | Store API | Admin API | Use Case |
+|------------|:---------:|:---------:|----------|
+| `both` | Yes | Yes | Public product specifications |
+| `front_end` | Yes | No | Customer-facing data |
+| `back_end` | No | Yes | Internal notes, integration IDs |
+
+## Supported Resources
+
+Metafields can be attached to most Spree resources including Products, Variants, Orders, Line Items, Taxons, Payments, Shipments, Gift Cards, Store Credits, and more.
+
+> **INFO:** Custom resources can also support metafields. See the [Customization Quickstart](/developer/customization/quickstart) for details.
+
+## Namespaces
+
+Namespaces organize metafields into logical groups and prevent key conflicts:
+
+| Namespace | Example Keys | Purpose |
+|-----------|-------------|---------|
+| `properties` | `manufacturer`, `material`, `fit` | Product specifications |
+| `shopify` | `product_id`, `variant_id` | Integration data |
+| `flags` | `featured`, `requires_approval` | Feature flags |
+| `custom` | `gift_message`, `delivery_notes` | Business-specific fields |
+
+> **INFO:** Namespace and key are automatically normalized to snake_case.
+
+## Store API
+
+Metafields with `display_on` set to `both` or `front_end` are included in Store API responses when you request the `metafields` expand:
+
+
+```typescript SDK
+const product = await client.products.get('spree-tote', {
+  expand: ['metafields'],
+})
+
+product.metafields?.forEach(metafield => {
+  console.log(metafield.key)   // "properties.manufacturer"
+  console.log(metafield.name)  // "Manufacturer"
+  console.log(metafield.value) // "Wilson"
+  console.log(metafield.type)  // "short_text"
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=metafields' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+**Response:**
+
+```json
+{
+  "id": "prod_86Rf07xd4z",
+  "name": "Spree T-Shirt",
+  "metafields": [
+    {
+      "id": "mf_k5nR8xLq",
+      "name": "Manufacturer",
+      "key": "properties.manufacturer",
+      "type": "short_text",
+      "value": "Wilson"
+    },
+    {
+      "id": "mf_m3Rp9wXz",
+      "name": "Material",
+      "key": "properties.material",
+      "type": "short_text",
+      "value": "100% Cotton"
+    }
+  ]
+}
+```
+
+> **NOTE:** The `display_on` attribute is intentionally excluded from Store API responses for security.
+
+## Admin Panel Management
+
+### Managing Definitions
+
+Navigate to **Settings → Metafield Definitions** in the Admin Panel to create and manage metafield definitions. Select the resource type, enter namespace and key, choose the data type, and set visibility.
+
+### Managing Values
+
+When editing a resource (e.g., a product), metafields appear in a dedicated section. The admin panel automatically builds forms for all defined metafields.
+
+## Metafields vs Metadata
+
+| Feature | Metafields | Metadata |
+|---------|-----------|----------|
+| Structure | Strongly typed, schema-defined | Flat key-value JSON |
+| Validation | Type-specific validation | None |
+| Visibility | Configurable (front/back/both) | Write-only in Store API |
+| Admin UI | Dedicated management forms | JSON preview |
+| Data Types | 6 specific types | Any JSON-serializable data |
+| Organization | Namespaced (`namespace.key`) | Flat structure |
+
+**Use Metafields** when you need type validation, visibility control, admin UI forms, or organized namespacing.
+
+**Use Metadata** for external system IDs, tracking attribution, or simple write-and-forget data.
+
+> **WARNING:** Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](/developer/upgrades/5.1-to-5.2#3-migrate-to-metafields-or-keep-using-properties).
+
+## Related Documentation
+
+- [Metadata](/developer/customization/metadata) — Simple key-value metadata
+- [Products](/developer/core-concepts/products) — Product catalog
+- [Events](/developer/core-concepts/events) — Subscribe to metafield events

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

@@ -0,0 +1,328 @@
+---
+title: Orders
+description: Order lifecycle, checkout flow, line items, payments, and shipments
+---
+
+## Overview
+
+An order is the central model connecting a customer to their purchase. It collects line items, addresses, shipments, payments, and adjustments into a single transaction that flows through a checkout state machine from cart to completion.
+
+```mermaid
+erDiagram
+    Order ||--o{ LineItem : "has many"
+    Order ||--o{ Shipment : "has many"
+    Order ||--o{ Payment : "has many"
+    Order ||--o{ Adjustment : "has many"
+    Order }o--|| Address : "ship_address"
+    Order }o--|| Address : "bill_address"
+    Order }o--|| User : "belongs to"
+    Order }o--|| Store : "belongs to"
+    LineItem }o--|| Variant : "belongs to"
+    Shipment }o--|| StockLocation : "ships from"
+    Payment }o--|| PaymentMethod : "belongs to"
+
+    Order {
+        string number
+        string state
+        string email
+        string currency
+        decimal total
+        string payment_state
+        string shipment_state
+    }
+
+    LineItem {
+        integer quantity
+        decimal price
+    }
+
+    Shipment {
+        string number
+        string state
+        string tracking
+    }
+
+    Payment {
+        decimal amount
+        string state
+    }
+```
+
+**Key relationships:**
+- **Line Items** link orders to [Variants](/developer/core-concepts/products#variants) (what was purchased)
+- **[Shipments](/developer/core-concepts/shipments)** handle fulfillment from stock locations
+- **[Payments](/developer/core-concepts/payments)** track payment attempts and their states
+- **[Adjustments](/developer/core-concepts/adjustments)** apply taxes, promotions, and shipping costs
+- **[Addresses](/developer/core-concepts/addresses)** store billing and shipping information
+
+## Order Attributes
+
+The API returns these key fields on every order:
+
+| Attribute | Description |
+|-----------|-------------|
+| `number` | Unique order number (e.g., `R123456789`), shown to customers |
+| `state` | Current checkout state (`cart`, `address`, `delivery`, `payment`, `confirm`, `complete`) |
+| `email` | Customer's email address |
+| `currency` | Order currency (e.g., `USD`) |
+| `item_count` | Total number of items |
+| `item_total` / `display_item_total` | Sum of line item prices |
+| `ship_total` / `display_ship_total` | Shipping cost |
+| `tax_total` / `display_tax_total` | Total tax |
+| `promo_total` / `display_promo_total` | Total discount from promotions |
+| `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + shipping + promos) |
+| `total` / `display_total` | Final order total |
+| `payment_state` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
+| `shipment_state` | Shipment status (`pending`, `ready`, `partial`, `shipped`, `backorder`) |
+| `completed_at` | Timestamp when the order was placed |
+
+The `display_*` fields return formatted strings with currency symbols (e.g., `"$15.99"`).
+
+## Cart
+
+A cart is simply an order in the `cart` state. Guest carts are identified by a cart token; authenticated users' carts are linked to their account.
+
+
+```typescript SDK
+// Create a cart
+const cart = await client.carts.create()
+// cart.token => "abc123" (save this for guest checkout)
+
+// Get existing cart
+const cart = await client.carts.get(cartId, { spreeToken: 'xxx' })
+
+// Add an item
+const updatedOrder = await client.carts.items.create(cart.id, {
+  variant_id: 'var_xxx',
+  quantity: 2,
+})
+
+// Update quantity
+await client.carts.items.update(cart.id, 'li_xxx', {
+  quantity: 3,
+})
+
+// Remove an item
+await client.carts.items.delete(cart.id, 'li_xxx')
+```
+
+```bash cURL
+# Create a cart
+curl -X POST 'https://api.mystore.com/api/v3/store/carts' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Get existing cart
+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123'
+
+# Add an item
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{ "variant_id": "var_xxx", "quantity": 2 }'
+
+# Update quantity
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{ "quantity": 3 }'
+
+# Remove an item
+curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123'
+```
+
+
+Every item mutation returns the full updated order with recalculated totals.
+
+## Checkout Flow
+
+The checkout is a state machine that advances the order through a series of steps. Each step collects required information before allowing the order to proceed.
+
+**Step 1: cart**
+
+Customer has items in their cart. This is the starting state.
+
+  **Step 2: address**
+
+Customer provides shipping and billing addresses.
+
+  **Step 3: delivery**
+
+Customer selects a shipping rate for each shipment.
+
+  **Step 4: payment**
+
+Customer provides payment. Skipped if the order is fully covered by store credit.
+
+  **Step 5: confirm**
+
+Customer reviews and confirms the order.
+
+  **Step 6: complete**
+
+Order is placed. `completed_at` is set and fulfillment begins.
+
+
+If the order doesn't meet the requirements for the next state (e.g., missing address), the API returns an error.
+
+
+```typescript SDK
+// Set addresses
+await client.carts.update(cartId, {
+  email: 'john@example.com',
+  ship_address: {
+    firstname: 'John', lastname: 'Doe',
+    address1: '123 Main St', city: 'Los Angeles',
+    country_iso: 'US', state_abbr: 'CA', zipcode: '90001',
+    phone: '555-0100',
+  },
+})
+
+// Get shipments and select a shipping rate
+const { data: shipments } = await client.carts.shipments.list(cartId)
+await client.carts.shipments.update(cartId, shipments[0].id, {
+  selected_shipping_rate_id: 'sr_xxx',
+})
+
+// Create a payment session (e.g., Stripe)
+const session = await client.carts.paymentSessions.create(cartId, {
+  payment_method_id: 'pm_xxx',
+})
+// session.external_data.client_secret => use with Stripe.js
+
+// Complete the payment session after provider confirmation
+await client.carts.paymentSessions.complete(cartId, session.id)
+
+// Complete the order
+await client.carts.complete(cartId)
+```
+
+```bash cURL
+# Set addresses
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "email": "john@example.com",
+    "ship_address": {
+      "firstname": "John", "lastname": "Doe",
+      "address1": "123 Main St", "city": "Los Angeles",
+      "country_iso": "US", "state_abbr": "CA", "zipcode": "90001",
+      "phone": "555-0100"
+    }
+  }'
+
+# Select a shipping rate
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{ "selected_shipping_rate_id": "sr_xxx" }'
+
+# Complete the order
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123'
+```
+
+
+## Coupon Codes
+
+Apply or remove promotional coupon codes during checkout:
+
+
+```typescript SDK
+// Apply a coupon
+await client.carts.couponCodes.apply(cartId, 'SAVE20')
+
+// Remove a coupon
+await client.carts.couponCodes.remove(cartId, 'SAVE20')
+```
+
+```bash cURL
+# Apply a coupon
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/coupon_codes' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{ "code": "SAVE20" }'
+
+# Remove a coupon
+curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/coupon_codes/SAVE20' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123'
+```
+
+
+## Order History
+
+Authenticated customers can view their past orders:
+
+
+```typescript SDK
+// List past orders
+const { data: orders } = await client.customer.orders.list()
+
+// Get a specific order with details
+const order = await client.orders.get('or_xxx', {
+  expand: ['items', 'shipments', 'payments'],
+})
+```
+
+```bash cURL
+# List past orders
+curl 'https://api.mystore.com/api/v3/store/customer/orders' \
+  -H 'Authorization: Bearer <jwt_token>'
+
+# Get a specific order
+curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=items,shipments,payments' \
+  -H 'Authorization: Bearer <jwt_token>'
+```
+
+
+## Line Items
+
+Line items represent individual products in an order. Each line item links to a [Variant](/developer/core-concepts/products#variants) and tracks the quantity and price at the time of purchase.
+
+When a variant is added to an order, the price is locked on the line item. If the variant's price changes later, existing orders are unaffected.
+
+## Adjustments
+
+[Adjustments](/developer/core-concepts/adjustments) modify an order's total — promotions decrease it, taxes and shipping increase it. Adjustments can be applied at the order level, the line item level, or the shipment level.
+
+## Payment States
+
+| State | Description |
+|-------|-------------|
+| `balance_due` | Payment total is less than the order total |
+| `paid` | Payment total equals the order total |
+| `credit_owed` | Payment total exceeds the order total (refund pending) |
+| `failed` | Most recent payment attempt failed |
+| `void` | Order was canceled and payments voided |
+
+## Shipment States
+
+| State | Description |
+|-------|-------------|
+| `pending` | All shipments are pending |
+| `ready` | All shipments are ready to ship |
+| `partial` | At least one shipment is shipped, others are not |
+| `shipped` | All shipments have been shipped |
+| `backorder` | Some inventory is on backorder |
+
+For more details, see [Shipments](/developer/core-concepts/shipments) and [Payments](/developer/core-concepts/payments).
+
+## Related Documentation
+
+- [Payments](/developer/core-concepts/payments) — Payment processing and payment sessions
+- [Shipments](/developer/core-concepts/shipments) — Fulfillment and shipping rates
+- [Addresses](/developer/core-concepts/addresses) — Billing and shipping addresses
+- [Promotions](/developer/core-concepts/promotions) — Discounts and coupon codes
+- [Checkout Customization](/developer/customization/checkout) — Customizing the checkout flow
+- [Events](/developer/core-concepts/events) — Subscribe to order events (e.g., `order.completed`)