Skip to content

Commit de65227

Browse files
devalogdevalog
authored
feat: expand guide section, use more components (#79)
1 parent 9b06f65 commit de65227

19 files changed

+1958
-33
lines changed

‎.claude/settings.local.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(mkdir:*)"
5+
],
6+
"deny": [],
7+
"ask": []
8+
}
9+
}

‎fern/docs.yml‎

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ layout:
1717

1818
tabs:
1919
home:
20-
display-name: Home
20+
display-name: Docs
2121
icon: home
2222
guides:
2323
display-name: Guides
@@ -35,13 +35,42 @@ navigation:
3535
path: docs/pages/welcome.mdx
3636
- tab: guides
3737
layout:
38-
- section: Learn
38+
- section: Get started
3939
contents:
40-
- page: Concepts
41-
path: docs/pages/concepts.mdx
42-
- page: SDKs
43-
path: docs/pages/sdks.mdx
44-
slug: sdks
40+
- page: Overview
41+
path: docs/pages/get-started/overview.mdx
42+
icon: fa-duotone fa-book-open
43+
- page: Quickstart
44+
path: docs/pages/get-started/quickstart.mdx
45+
icon: fa-duotone fa-rocket
46+
- section: Capabilities
47+
contents:
48+
- page: Plant management
49+
path: docs/pages/capabilities/plant-management.mdx
50+
icon: fa-duotone fa-seedling
51+
- page: Order processing
52+
path: docs/pages/capabilities/order-processing.mdx
53+
icon: fa-duotone fa-cart-shopping
54+
- page: Customer management
55+
path: docs/pages/capabilities/customer-management.mdx
56+
icon: fa-duotone fa-users
57+
- page: Inventory tracking
58+
path: docs/pages/capabilities/inventory-tracking.mdx
59+
icon: fa-duotone fa-boxes-stacked
60+
- section: Tutorials
61+
contents:
62+
- page: Searching for plants
63+
path: docs/pages/tutorials/searching-plants.mdx
64+
icon: fa-duotone fa-magnifying-glass
65+
- page: Creating your first order
66+
path: docs/pages/tutorials/first-order-tutorial.mdx
67+
icon: fa-duotone fa-bag-shopping
68+
- page: Managing plant inventory
69+
path: docs/pages/tutorials/inventory-tutorial.mdx
70+
icon: fa-duotone fa-clipboard-list
71+
- section: Changelog
72+
contents:
73+
- changelog: docs/changelog
4574
- tab: API Reference
4675
layout:
4776
- api: API Reference

‎fern/docs/changelog/09-01-2025.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: September 1, 2025
3+
slug: 09-01-2025
4+
tags: ["plants-api", "orders", "webhooks", "security"]
5+
---
6+
7+
## New features
8+
9+
### Order refunds API
10+
Introduced comprehensive refund management:
11+
- `POST /orders/{id}/refund` - Process full or partial refunds
12+
- `GET /orders/{id}/refunds` - View refund history
13+
- Automatic inventory restoration on refunded items
14+
15+
### Webhook signature verification
16+
All webhooks now include `x-plantstore-signature` header for verifying webhook authenticity using HMAC-SHA256.
17+
18+
## Enhancements
19+
20+
- Added `description` field to plant objects for detailed product information
21+
- Customer addresses can now be labeled (e.g., "Home", "Work", "Gift Address")
22+
- Improved API response times by 40% through database optimization
23+
24+
## Documentation
25+
26+
- Added new tutorial: "Managing plant inventory"
27+
- Updated webhook setup guide with signature verification examples
28+
- Added code samples for Python, JavaScript, and Go SDKs

‎fern/docs/changelog/09-15-2025.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: September 15, 2025
3+
slug: 09-15-2025
4+
tags: ["plants-api", "search", "new-features", "plant-care"]
5+
---
6+
7+
## New features
8+
9+
### Plant care requirements
10+
Added detailed care information to plant objects:
11+
- `light_requirements` - Light level needs (low, medium, bright indirect, full sun)
12+
- `water_frequency` - Watering schedule recommendations
13+
- `temperature_range` - Ideal temperature range
14+
- `humidity_level` - Humidity preferences
15+
16+
### Advanced filtering
17+
Plant search now supports filtering by care requirements:
18+
```bash
19+
GET /plants?care_level=easy&light_requirements=low
20+
```
21+
22+
## Enhancements
23+
24+
- Increased rate limit from 1000 to 5000 requests per hour for production API keys
25+
- Added response caching headers to improve performance
26+
- Order confirmation emails now include estimated delivery date
27+
28+
## Bug fixes
29+
30+
- Fixed pagination issue in customer order history
31+
- Resolved incorrect stock calculations when orders were cancelled

‎fern/docs/changelog/10-01-2025.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: October 1, 2025
3+
slug: 10-01-2025
4+
tags: ["plants-api", "breaking-change", "customers", "orders"]
5+
---
6+
7+
## New features
8+
9+
### Customer loyalty program
10+
Introduced new `/customers/{id}/loyalty` endpoint for accessing customer loyalty points and rewards.
11+
12+
### Wishlist functionality
13+
Customers can now maintain wishlists:
14+
- `POST /customers/{id}/wishlist` - Add plants to wishlist
15+
- `GET /customers/{id}/wishlist` - Retrieve wishlist
16+
- `DELETE /customers/{id}/wishlist/{plant_id}` - Remove from wishlist
17+
18+
## Breaking changes
19+
20+
### Order status field
21+
The order `status` field now uses standardized values. Legacy status values will be deprecated on December 1, 2025:
22+
- `pending_payment` → `pending`
23+
- `in_progress` → `processing`
24+
25+
Please update your integrations to use the new values.
26+
27+
## Enhancements
28+
29+
- Added pagination support to `/plants` endpoint with `limit` and `offset` parameters
30+
- Improved error messages with more detailed validation feedback

‎fern/docs/changelog/10-15-2025.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: October 15, 2025
3+
slug: 10-15-2025
4+
tags: ["plants-api", "webhooks", "inventory-management", "new-features"]
5+
---
6+
7+
## New features
8+
9+
### Webhook events
10+
Added support for new webhook events:
11+
- `inventory.low_stock` - Triggered when stock falls below reorder point
12+
- `inventory.restocked` - Triggered when items are restocked
13+
- `customer.updated` - Triggered when customer profile is modified
14+
15+
### Multi-location inventory
16+
Inventory endpoints now support `location` parameter for tracking stock across multiple warehouses and greenhouses.
17+
18+
## Enhancements
19+
20+
- Improved webhook retry logic with exponential backoff
21+
- Added `tracking_number` and `carrier` fields to order responses

‎fern/docs/changelog/10-29-2025.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: October 29, 2025
3+
slug: 10-29-2025
4+
tags: ["plants-api", "inventory-management", "enhancements"]
5+
---
6+
7+
## Enhancements
8+
9+
### Inventory tracking improvements
10+
Added new `reserved` field to inventory responses, allowing better tracking of stock allocated to pending orders.
11+
12+
### Bulk operations
13+
Introduced `/inventory/batch-update` endpoint for updating multiple plant inventory levels in a single request.
14+
15+
## Bug fixes
16+
17+
- Fixed an issue where low stock alerts weren't triggering when inventory reached exactly the reorder point
18+
- Corrected timezone handling in inventory history timestamps

‎fern/docs/pages/capabilities/customer-management.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Customer management
3+
subtitle: Build lasting customer relationships with comprehensive profile and preference tracking
4+
slug: customer-management
5+
---
6+
7+
## Overview
8+
9+
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.
10+
11+
<CardGroup cols={2}>
12+
<Card
13+
title="Creating your first order"
14+
icon="duotone book-sparkles"
15+
href="/first-order-tutorial"
16+
>
17+
Learn how to create customers as part of the order flow.
18+
</Card>
19+
<Card
20+
title="API reference"
21+
icon="duotone code"
22+
href="/api-reference"
23+
>
24+
Explore customer endpoints and schemas.
25+
</Card>
26+
</CardGroup>
27+
28+
## Customer data types
29+
30+
Different types of customer data serve different purposes in your system.
31+
32+
| Data type | What it includes | Primary use |
33+
|-----------|------------------|-------------|
34+
| **Identity** | Name, email, phone, customer ID | Order fulfillment, authentication |
35+
| **Preferences** | Email/SMS settings, language, timezone | Marketing, communication |
36+
| **Transactional** | Order history, total spend, returns | Loyalty programs, segmentation |
37+
| **Addresses** | Multiple shipping addresses, labels | Faster checkout, gift shipping |
38+
39+
<Note>
40+
Only collect data you'll actually use. More data means more liability and compliance requirements. Keep it minimal and purposeful.
41+
</Note>
42+
43+
## Address management
44+
45+
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.
46+
47+
<Tip>
48+
Address validation during input prevents expensive shipping errors. Most shipping carriers provide free address validation APIs.
49+
</Tip>
50+
51+
## Privacy and compliance
52+
53+
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.
54+
55+
| Regulation | Applies to | Key requirement |
56+
|------------|------------|-----------------|
57+
| GDPR | EU customers | Right to access, export, and delete data |
58+
| CCPA | California customers | Right to know what data is collected |
59+
| CAN-SPAM | Email marketing | Easy unsubscribe, accurate sender info |
60+
61+
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.
62+
63+
<Warning>
64+
Never commit customer data or API keys to version control. Use environment variables and secrets management instead.
65+
</Warning>
66+
67+
## Customer segmentation
68+
69+
Group customers for targeted engagement and personalized experiences.
70+
71+
| Segment by | Example groups | Use case |
72+
|------------|----------------|----------|
73+
| **Purchase behavior** | High-value, frequent, one-time, at-risk | Loyalty rewards, win-back campaigns |
74+
| **Product preference** | Indoor enthusiasts, succulent collectors | Product recommendations |
75+
| **Engagement** | Highly engaged, moderate, dormant | Email frequency, re-engagement |
76+
77+
Segmentation enables more effective marketing by tailoring messages to customer interests and behavior patterns.

‎fern/docs/pages/capabilities/inventory-tracking.mdx‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Inventory tracking
3+
subtitle: Track plant stock levels in real-time with automated alerts and reservations
4+
slug: inventory-tracking
5+
---
6+
7+
## Overview
8+
9+
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.
10+
11+
<CardGroup cols={2}>
12+
<Card
13+
title="Managing plant inventory"
14+
icon="duotone book-sparkles"
15+
href="/inventory-tutorial"
16+
>
17+
Learn how to track and update your plant stock.
18+
</Card>
19+
<Card
20+
title="API reference"
21+
icon="duotone code"
22+
href="/api-reference"
23+
>
24+
Explore inventory endpoints and schemas.
25+
</Card>
26+
</CardGroup>
27+
28+
## Inventory states
29+
30+
Inventory isn't just a single number. Plants exist in different states throughout the order and fulfillment process.
31+
32+
| State | Definition | Formula |
33+
|-------|------------|---------|
34+
| **On-hand** | Physical count in your possession | Actual count from warehouse |
35+
| **Reserved** | Committed to pending orders | Sum of active order reservations |
36+
| **Available** | Stock available for new orders | On-hand - Reserved - Damaged |
37+
| **In-transit** | Ordered from suppliers, not yet received | Active purchase orders |
38+
39+
<Warning>
40+
Update inventory in real-time, not in batches. Delays between order creation and inventory updates cause overselling.
41+
</Warning>
42+
43+
## Reservation strategy
44+
45+
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.
46+
47+
<Tip>
48+
Most payment processors complete checkout within 15 minutes. Setting reservation expiration to 15-30 minutes balances preventing overselling with not holding stock unnecessarily.
49+
</Tip>
50+
51+
## Low-stock alerts
52+
53+
Set reorder points based on supplier lead time and sales velocity to ensure you never run out of popular plants.
54+
55+
**Reorder point formula:** `(Lead time in days × Daily sales) + Safety stock`
56+
57+
| Component | Example | Purpose |
58+
|-----------|---------|---------|
59+
| Lead time | 7 days | How long to get new stock from supplier |
60+
| Daily sales | 2 plants/day | Average sales velocity |
61+
| Safety stock | 5 plants | Buffer for demand spikes or delays |
62+
| **Reorder point** | **19 plants** | Alert when inventory drops below this |
63+
64+
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.
65+
66+
## Accuracy and auditing
67+
68+
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.
69+
70+
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.
71+
72+
| Change type | Reason code | Approval required |
73+
|-------------|-------------|-------------------|
74+
| Stock received | `shipment_received` | No |
75+
| Order shipped | `order_fulfilled` | No |
76+
| Damaged goods | `shrinkage_damaged` | Manager approval |
77+
| Manual adjustment | `count_correction` | Manager approval |
78+
79+
<Note>
80+
Plants are trickier than most inventory due to perishability, growth, and quality variance. Regular physical counts catch issues before they impact customers.
81+
</Note>
82+
83+
## Multi-location inventory
84+
85+
For operations with multiple greenhouses, warehouses, or stores, choose a strategy that balances complexity with delivery speed.
86+
87+
| Strategy | Best for | Trade-offs |
88+
|----------|----------|------------|
89+
| **Centralized** | Small operations, specialty items | Simpler to manage, slower/costlier shipping |
90+
| **Distributed** | Large operations, fast delivery needs | Faster delivery, more complex management |
91+
| **Hybrid** | Most operations | Popular items everywhere, specialty items central | Balanced approach |
92+
93+
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.

0 commit comments

Comments
 (0)