fern-api · devalog · Nov 3, 2025 · Oct 29, 2025 · Nov 3, 2025
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}
diff --git a/fern/docs.yml b/fern/docs.yml
@@ -17,7 +17,7 @@ layout:
 
 tabs:
   home:
-    display-name: Home
+    display-name: Docs
     icon: home
   guides:
     display-name: Guides
@@ -35,13 +35,42 @@ navigation:
             path: docs/pages/welcome.mdx
   - tab: guides
     layout:
-      - section: Learn
+      - section: Get started
         contents:
-          - page: Concepts
-            path: docs/pages/concepts.mdx
-          - page: SDKs
-            path: docs/pages/sdks.mdx
-            slug: sdks
+          - page: Overview
+            path: docs/pages/get-started/overview.mdx
+            icon: fa-duotone fa-book-open
+          - page: Quickstart
+            path: docs/pages/get-started/quickstart.mdx
+            icon: fa-duotone fa-rocket
+      - section: Capabilities
+        contents:
+          - page: Plant management
+            path: docs/pages/capabilities/plant-management.mdx
+            icon: fa-duotone fa-seedling
+          - page: Order processing
+            path: docs/pages/capabilities/order-processing.mdx
+            icon: fa-duotone fa-cart-shopping
+          - page: Customer management
+            path: docs/pages/capabilities/customer-management.mdx
+            icon: fa-duotone fa-users
+          - page: Inventory tracking
+            path: docs/pages/capabilities/inventory-tracking.mdx
+            icon: fa-duotone fa-boxes-stacked
+      - section: Tutorials
+        contents:
+          - page: Searching for plants
+            path: docs/pages/tutorials/searching-plants.mdx
+            icon: fa-duotone fa-magnifying-glass
+          - page: Creating your first order
+            path: docs/pages/tutorials/first-order-tutorial.mdx
+            icon: fa-duotone fa-bag-shopping
+          - page: Managing plant inventory
+            path: docs/pages/tutorials/inventory-tutorial.mdx
+            icon: fa-duotone fa-clipboard-list
+      - section: Changelog
+        contents:
+          - changelog: docs/changelog
   - tab: API Reference
     layout:
       - api: API Reference

diff --git a/fern/docs/changelog/09-01-2025.mdx b/fern/docs/changelog/09-01-2025.mdx
@@ -0,0 +1,28 @@
+---
+title: September 1, 2025
+slug: 09-01-2025
+tags: ["plants-api", "orders", "webhooks", "security"]
+---
+
+## New features
+
+### Order refunds API
+Introduced comprehensive refund management:
+- `POST /orders/{id}/refund` - Process full or partial refunds
+- `GET /orders/{id}/refunds` - View refund history
+- Automatic inventory restoration on refunded items
+
+### Webhook signature verification
+All webhooks now include `x-plantstore-signature` header for verifying webhook authenticity using HMAC-SHA256.
+
+## Enhancements
+
+- Added `description` field to plant objects for detailed product information
+- Customer addresses can now be labeled (e.g., "Home", "Work", "Gift Address")
+- Improved API response times by 40% through database optimization
+
+## Documentation
+
+- Added new tutorial: "Managing plant inventory"
+- Updated webhook setup guide with signature verification examples
+- Added code samples for Python, JavaScript, and Go SDKs
diff --git a/fern/docs/changelog/09-15-2025.mdx b/fern/docs/changelog/09-15-2025.mdx
@@ -0,0 +1,31 @@
+---
+title: September 15, 2025
+slug: 09-15-2025
+tags: ["plants-api", "search", "new-features", "plant-care"]
+---
+
+## New features
+
+### Plant care requirements
+Added detailed care information to plant objects:
+- `light_requirements` - Light level needs (low, medium, bright indirect, full sun)
+- `water_frequency` - Watering schedule recommendations
+- `temperature_range` - Ideal temperature range
+- `humidity_level` - Humidity preferences
+
+### Advanced filtering
+Plant search now supports filtering by care requirements:
+```bash
+GET /plants?care_level=easy&light_requirements=low
+```
+
+## Enhancements
+
+- Increased rate limit from 1000 to 5000 requests per hour for production API keys
+- Added response caching headers to improve performance
+- Order confirmation emails now include estimated delivery date
+
+## Bug fixes
+
+- Fixed pagination issue in customer order history
+- Resolved incorrect stock calculations when orders were cancelled
diff --git a/fern/docs/changelog/10-01-2025.mdx b/fern/docs/changelog/10-01-2025.mdx
@@ -0,0 +1,30 @@
+---
+title: October 1, 2025
+slug: 10-01-2025
+tags: ["plants-api", "breaking-change", "customers", "orders"]
+---
+
+## New features
+
+### Customer loyalty program
+Introduced new `/customers/{id}/loyalty` endpoint for accessing customer loyalty points and rewards.
+
+### Wishlist functionality
+Customers can now maintain wishlists:
+- `POST /customers/{id}/wishlist` - Add plants to wishlist
+- `GET /customers/{id}/wishlist` - Retrieve wishlist
+- `DELETE /customers/{id}/wishlist/{plant_id}` - Remove from wishlist
+
+## Breaking changes
+
+### Order status field
+The order `status` field now uses standardized values. Legacy status values will be deprecated on December 1, 2025:
+- `pending_payment` → `pending`
+- `in_progress` → `processing`
+
+Please update your integrations to use the new values.
+
+## Enhancements
+
+- Added pagination support to `/plants` endpoint with `limit` and `offset` parameters
+- Improved error messages with more detailed validation feedback
diff --git a/fern/docs/changelog/10-15-2025.mdx b/fern/docs/changelog/10-15-2025.mdx
@@ -0,0 +1,21 @@
+---
+title: October 15, 2025
+slug: 10-15-2025
+tags: ["plants-api", "webhooks", "inventory-management", "new-features"]
+---
+
+## New features
+
+### Webhook events
+Added support for new webhook events:
+- `inventory.low_stock` - Triggered when stock falls below reorder point
+- `inventory.restocked` - Triggered when items are restocked
+- `customer.updated` - Triggered when customer profile is modified
+
+### Multi-location inventory
+Inventory endpoints now support `location` parameter for tracking stock across multiple warehouses and greenhouses.
+
+## Enhancements
+
+- Improved webhook retry logic with exponential backoff
+- Added `tracking_number` and `carrier` fields to order responses
diff --git a/fern/docs/changelog/10-29-2025.mdx b/fern/docs/changelog/10-29-2025.mdx
@@ -0,0 +1,18 @@
+---
+title: October 29, 2025
+slug: 10-29-2025
+tags: ["plants-api", "inventory-management", "enhancements"]
+---
+
+## Enhancements
+
+### Inventory tracking improvements
+Added new `reserved` field to inventory responses, allowing better tracking of stock allocated to pending orders.
+
+### Bulk operations
+Introduced `/inventory/batch-update` endpoint for updating multiple plant inventory levels in a single request.
+
+## Bug fixes
+
+- Fixed an issue where low stock alerts weren't triggering when inventory reached exactly the reorder point
+- Corrected timezone handling in inventory history timestamps
diff --git a/fern/docs/pages/capabilities/customer-management.mdx b/fern/docs/pages/capabilities/customer-management.mdx
@@ -0,0 +1,77 @@
+---
+title: Customer management
+subtitle: Build lasting customer relationships with comprehensive profile and preference tracking
+slug: customer-management
+---
+
+## Overview
+
+The Plant Store API's customer management capabilities help you build and maintain customer relationships through detailed profiles, preferences, and purchase history. Use it to create and manage customer profiles, track order history, manage multiple shipping addresses, store communication preferences, and build loyalty programs.
+
+<CardGroup cols={2}>
+  <Card
+    title="Creating your first order"
+    icon="duotone book-sparkles"
+    href="/first-order-tutorial"
+  >
+    Learn how to create customers as part of the order flow.
+  </Card>
+  <Card
+    title="API reference"
+    icon="duotone code"
+    href="/api-reference"
+  >
+    Explore customer endpoints and schemas.
+  </Card>
+</CardGroup>
+
+## Customer data types
+
+Different types of customer data serve different purposes in your system.
+
+| Data type | What it includes | Primary use |
+|-----------|------------------|-------------|
+| **Identity** | Name, email, phone, customer ID | Order fulfillment, authentication |
+| **Preferences** | Email/SMS settings, language, timezone | Marketing, communication |
+| **Transactional** | Order history, total spend, returns | Loyalty programs, segmentation |
+| **Addresses** | Multiple shipping addresses, labels | Faster checkout, gift shipping |
+
+<Note>
+Only collect data you'll actually use. More data means more liability and compliance requirements. Keep it minimal and purposeful.
+</Note>
+
+## Address management
+
+Customers often ship to multiple locations like home, office, or gift recipients. Support multiple saved addresses with labels like "Home" or "Mom's house" for easy selection. Validate addresses at entry to reduce shipping errors and allow customers to set a default shipping address for faster checkout.
+
+<Tip>
+Address validation during input prevents expensive shipping errors. Most shipping carriers provide free address validation APIs.
+</Tip>
+
+## Privacy and compliance
+
+Customer data requires careful handling to maintain trust and meet legal requirements. Encrypt sensitive data at rest and in transit, support GDPR data export and deletion requests, and implement secure password requirements. Log all access to customer data for audit trails.
+
+| Regulation | Applies to | Key requirement |
+|------------|------------|-----------------|
+| GDPR | EU customers | Right to access, export, and delete data |
+| CCPA | California customers | Right to know what data is collected |
+| CAN-SPAM | Email marketing | Easy unsubscribe, accurate sender info |
+
+Retain customer data only as long as it's useful and compliant. Active customers can be kept indefinitely, inactive customers for 3-7 years, and deleted accounts only what's legally required for tax and transaction records.
+
+<Warning>
+Never commit customer data or API keys to version control. Use environment variables and secrets management instead.
+</Warning>
+
+## Customer segmentation
+
+Group customers for targeted engagement and personalized experiences.
+
+| Segment by | Example groups | Use case |
+|------------|----------------|----------|
+| **Purchase behavior** | High-value, frequent, one-time, at-risk | Loyalty rewards, win-back campaigns |
+| **Product preference** | Indoor enthusiasts, succulent collectors | Product recommendations |
+| **Engagement** | Highly engaged, moderate, dormant | Email frequency, re-engagement |
+
+Segmentation enables more effective marketing by tailoring messages to customer interests and behavior patterns.
diff --git a/fern/docs/pages/capabilities/inventory-tracking.mdx b/fern/docs/pages/capabilities/inventory-tracking.mdx
@@ -0,0 +1,93 @@
+---
+title: Inventory tracking
+subtitle: Track plant stock levels in real-time with automated alerts and reservations
+slug: inventory-tracking
+---
+
+## Overview
+
+The Plant Store API's inventory tracking capabilities help you maintain accurate stock levels and prevent overselling. Use it to track on-hand, reserved, and available quantities, reserve inventory when orders are placed, set up automatic low-stock alerts, view inventory history and audit trails, and manage stock across multiple locations.
+
+<CardGroup cols={2}>
+  <Card
+    title="Managing plant inventory"
+    icon="duotone book-sparkles"
+    href="/inventory-tutorial"
+  >
+    Learn how to track and update your plant stock.
+  </Card>
+  <Card
+    title="API reference"
+    icon="duotone code"
+    href="/api-reference"
+  >
+    Explore inventory endpoints and schemas.
+  </Card>
+</CardGroup>
+
+## Inventory states
+
+Inventory isn't just a single number. Plants exist in different states throughout the order and fulfillment process.
+
+| State | Definition | Formula |
+|-------|------------|---------|
+| **On-hand** | Physical count in your possession | Actual count from warehouse |
+| **Reserved** | Committed to pending orders | Sum of active order reservations |
+| **Available** | Stock available for new orders | On-hand - Reserved - Damaged |
+| **In-transit** | Ordered from suppliers, not yet received | Active purchase orders |
+
+<Warning>
+Update inventory in real-time, not in batches. Delays between order creation and inventory updates cause overselling.
+</Warning>
+
+## Reservation strategy
+
+Reserve inventory when an order is created (not just when paid) to prevent two customers from buying the last plant simultaneously. Set expiration times for unpaid orders—typically 15-30 minutes—and release reservations automatically if payment fails or times out. Convert reservations to permanent deductions when the order ships.
+
+<Tip>
+Most payment processors complete checkout within 15 minutes. Setting reservation expiration to 15-30 minutes balances preventing overselling with not holding stock unnecessarily.
+</Tip>
+
+## Low-stock alerts
+
+Set reorder points based on supplier lead time and sales velocity to ensure you never run out of popular plants.
+
+**Reorder point formula:** `(Lead time in days × Daily sales) + Safety stock`
+
+| Component | Example | Purpose |
+|-----------|---------|---------|
+| Lead time | 7 days | How long to get new stock from supplier |
+| Daily sales | 2 plants/day | Average sales velocity |
+| Safety stock | 5 plants | Buffer for demand spikes or delays |
+| **Reorder point** | **19 plants** | Alert when inventory drops below this |
+
+Automate reorder notifications via email or webhook when inventory drops below the reorder point. Track supplier lead times over time and adjust reorder points accordingly to account for seasonal variations or supply chain changes.
+
+## Accuracy and auditing
+
+Maintain inventory accuracy through regular physical counts and comprehensive audit trails. Use cycle counting—counting a different section each week rather than everything at once. High-value or fast-moving items should be counted weekly, while slow-movers can be quarterly.
+
+Log all inventory changes with timestamps, reasons, and the user who made the change. This creates an audit trail for troubleshooting discrepancies and preventing fraud.
+
+| Change type | Reason code | Approval required |
+|-------------|-------------|-------------------|
+| Stock received | `shipment_received` | No |
+| Order shipped | `order_fulfilled` | No |
+| Damaged goods | `shrinkage_damaged` | Manager approval |
+| Manual adjustment | `count_correction` | Manager approval |
+
+<Note>
+Plants are trickier than most inventory due to perishability, growth, and quality variance. Regular physical counts catch issues before they impact customers.
+</Note>
+
+## Multi-location inventory
+
+For operations with multiple greenhouses, warehouses, or stores, choose a strategy that balances complexity with delivery speed.
+
+| Strategy | Best for | Trade-offs |
+|----------|----------|------------|
+| **Centralized** | Small operations, specialty items | Simpler to manage, slower/costlier shipping |
+| **Distributed** | Large operations, fast delivery needs | Faster delivery, more complex management |
+| **Hybrid** | Most operations | Popular items everywhere, specialty items central | Balanced approach |
+
+Route orders to the optimal location based on proximity to customer, current stock availability, and shipping costs. Allow transfers between locations for balancing inventory across facilities.