Menu
Manage Japanese EC shops on BASE and STORES — products, orders, inventory for instant-commerce
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Manage projects on Nulab Backlog — issues, wikis, milestones, Git, sprints for Japan's top PM tool
Automate Japan's
Unified Gmail, Calendar, Drive, Sheets, and Docs management from Claude Code
Task and project management on Jooto — create tasks, manage boards, automate workflows via PR TIMES' tool
Attendance and time tracking automation — daily/monthly data, payroll sync via Japan's leading attendance system
Build, query, and automate Cybozu kintone apps — Japan's leading no-code business platform
| name | base-stores-agent |
| description | Manage Japanese EC shops on BASE and STORES — products, orders, inventory for instant-commerce |
| author | hanabi-jpn |
| version | 1.0.0 |
| tags | ["ecommerce","base","stores","japan-ec","product-management","inventory","order-management","instant-commerce"] |
╔══════════════════════════════════════════════════════════════╗
║ ║
║ ██████╗ █████╗ ███████╗███████╗ ██╗ ║
║ ██╔══██╗██╔══██╗██╔════╝██╔════╝ ██╬╝ ║
║ ██████╔╝███████║███████╗█████╗ ███████╗ ║
║ ██╔══██╗██╔══██║╚════██║██╔══╝ ╚══██╔═╝ ║
║ ██████╔╝██║ ██║███████║███████╗ ╚═╝ ║
║ ╚═════╝ ╚═╝ ╚═╝╚══════╝╚══════╝ ║
║ ███████╗████████╗ ██████╗ ██████╗ ███████╗███████╗ ║
║ ██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗██╔════╝██╔════╝ ║
║ ███████╗ ██║ ██║ ██║██████╔╝█████╗ ███████╗ ║
║ ╚════██║ ██║ ██║ ██║██╔══██╗██╔══╝ ╚════██║ ║
║ ███████║ ██║ ╚██████╔╝██║ ██║███████╗███████║ ║
║ ╚══════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝╚══════╝ ║
║ ║
║ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ║
║ │ Shop │───>│ Cart │───>│ Pay │───>│ Ship │ ║
║ └──────┘ └──────┘ └──────┘ └──────┘ ║
╚══════════════════════════════════════════════════════════════╝
claude-code base stores ecommerce japan
Unify your BASE and STORES shops under one command line -- manage products, fulfill orders, and sync inventory across Japan's top instant-commerce platforms.
BASE and STORES are the two dominant instant-commerce platforms in Japan, together powering over 2 million online shops. BASE alone hosts 1.4 million shops and has become the go-to platform for individual creators, small businesses, and D2C brands launching their first online store. STORES (by STORES, Inc., formerly hey, Inc.) serves a similarly vibrant ecosystem with its seamless storefront builder and integrated payment processing. Despite their popularity, both platforms offer limited bulk management tooling, forcing shop owners to perform repetitive manual operations through web dashboards.
BASE & STORES Agent solves this by providing a unified CLI that speaks both the BASE API and STORES API fluently. You can list products across both platforms, synchronize inventory in real time, process orders in bulk, generate consolidated sales analytics, and manage customer data -- all from a single terminal session. The agent intelligently routes commands to the correct platform based on your configuration, or you can explicitly target one platform with the --platform base or --platform stores flag. For shops that sell on both BASE and STORES simultaneously, the inventory sync feature ensures stock levels stay consistent, preventing overselling and stockouts.
Architecture Overview
=====================
┌──────────────┐ ┌───────────────────────┐
│ Terminal │ │ BASE & STORES Agent │
│ │ │ │
│ ec products │────────>│ ┌─────────────────┐ │
│ ec orders │ │ │ Platform Router │ │
│ ec sync │ │ └────────┬────────┘ │
│ ec analytics│ │ │ │
└──────────────┘ │ ┌─────┴─────┐ │
│ ▼ ▼ │
│ ┌──────┐ ┌────────┐ │
│ │ BASE │ │ STORES │ │
│ │ API │ │ API │ │
│ │ v1 │ │ v1 │ │
│ └──┬───┘ └───┬────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────┐ │
│ │ Unified Data │ │
│ │ Normalizer │ │
│ └──────────────────┘ │
└───────────────────────┘
│
┌──────────▼──────────┐
│ ~/.ec-agent/ │
│ - inventory.db │
│ - sync-log.json │
│ - analytics-cache │
└─────────────────────┘
You are the BASE & STORES Agent, an expert in Japanese instant-commerce platform management. Follow these rules precisely:
BASE_ACCESS_TOKEN for BASE operations and STORES_ACCESS_TOKEN for STORES operations. Both tokens can be active simultaneously for cross-platform workflows.BASE_CLIENT_ID and BASE_CLIENT_SECRET to initiate token generation. Guide the user through the OAuth2 authorization code flow if no access token is set.--platform base or --platform stores is specified.--limit and --offset for pagination. Display platform origin with a [B] or [S] prefix.[NEW], [PAID], [SHIPPED], [DELIVERED], [CANCELLED]. Map platform-specific statuses to these unified labels.--confirm flag to prevent accidental mass changes.--refresh flag forces a fresh API call.~/.ec-agent/audit.log with timestamps and before/after values.+5, -3, = for unchanged items.| Variable | Required | Default | Description |
|---|---|---|---|
BASE_CLIENT_ID | Yes (BASE) | -- | BASE OAuth2 client ID |
BASE_CLIENT_SECRET | Yes (BASE) | -- | BASE OAuth2 client secret |
BASE_ACCESS_TOKEN | Yes (BASE) | -- | BASE API access token |
STORES_ACCESS_TOKEN | Yes (STORES) | -- | STORES API access token |
EC_DEFAULT_PLATFORM | No | both | Default platform: base, stores, both |
EC_CURRENCY_DISPLAY | No | jpy | Currency display format |
EC_CACHE_TTL | No | 600 | Cache TTL in seconds |
EC_CSV_ENCODING | No | shift-jis | Default CSV encoding for exports |
ec products -- List Products$ ec products
┌──────┬─────┬────────────────────────────────┬──────────┬───────┬───────────┐
│ # │ Src │ Title │ Price │ Stock │ Status │
├──────┼─────┼────────────────────────────────┼──────────┼───────┼───────────┤
│ 001 │ [B] │ Hand-dyed indigo tote bag │ ¥4,980 │ 12 │ Published │
│ 002 │ [B] │ Ceramic matcha bowl (wabi) │ ¥3,200 │ 8 │ Published │
│ 003 │ [S] │ Organic cotton t-shirt │ ¥2,980 │ 45 │ Published │
│ 004 │ [S] │ Hinoki wood phone stand │ ¥1,500 │ 30 │ Published │
│ 005 │ [B] │ Washi paper notebook A5 │ ¥1,200 │ 67 │ Draft │
│ 006 │ [S] │ Beeswax food wraps (3-pack) │ ¥1,800 │ 22 │ Published │
└──────┴─────┴────────────────────────────────┴──────────┴───────┴───────────┘
Showing 6 of 41 products | BASE: 23 | STORES: 18
ec orders -- View Orders$ ec orders --period 2026-02
┌────────────┬─────┬──────────────────────┬──────────┬───────────┬────────────┐
│ Order ID │ Src │ Customer │ Total │ Status │ Date │
├────────────┼─────┼──────────────────────┼──────────┼───────────┼────────────┤
│ B-20260228 │ [B] │ Nakamura Haruki │ ¥8,180 │ [SHIPPED] │ 2026-02-28 │
│ S-20260227 │ [S] │ Watanabe Rina │ ¥2,980 │ [PAID] │ 2026-02-27 │
│ B-20260226 │ [B] │ Kobayashi Sota │ ¥4,980 │ [DELIVRD] │ 2026-02-26 │
│ S-20260225 │ [S] │ Ito Sakura │ ¥3,300 │ [DELIVRD] │ 2026-02-25 │
│ B-20260224 │ [B] │ Takahashi Ryo │ ¥6,400 │ [DELIVRD] │ 2026-02-24 │
└────────────┴─────┴──────────────────────┴──────────┴───────────┴────────────┘
5 orders in February 2026 | Revenue: ¥25,840 | BASE: ¥19,560 | STORES: ¥6,280
ec inventory -- Check Inventory$ ec inventory --low-stock 10
Low Stock Alert (threshold: 10 units)
┌─────┬────────────────────────────────┬───────┬───────┬──────────┐
│ Src │ Product │ Stock │ Sold │ Velocity │
├─────┼────────────────────────────────┼───────┼───────┼──────────┤
│ [B] │ Ceramic matcha bowl (wabi) │ 8 │ 42 │ 2.1/week │
│ [B] │ Hand-dyed indigo scarf │ 3 │ 28 │ 1.4/week │
│ [S] │ Yuzu body butter 100ml │ 5 │ 35 │ 1.8/week │
└─────┴────────────────────────────────┴───────┴───────┴──────────┘
3 products below threshold | Restock recommended within 1-2 weeks
ec analytics -- Sales Analytics$ ec analytics --period 2026-02
═══════════════════════════════════════════════════════
Sales Report: February 2026 | Both Platforms
═══════════════════════════════════════════════════════
Revenue: ¥387,200
BASE: ¥248,600 (64.2%)
STORES: ¥138,600 (35.8%)
Orders: 89
Avg Order Value: ¥4,350
Unique Customers: 76
Top Products:
1. Hand-dyed indigo tote bag ¥74,700 (15 sold)
2. Ceramic matcha bowl (wabi) ¥44,800 (14 sold)
3. Organic cotton t-shirt ¥38,740 (13 sold)
Weekly Trend:
W1: ¥82,400 ████████████████
W2: ¥104,300 ████████████████████
W3: ¥96,100 ███████████████████
W4: ¥104,400 ████████████████████
ec customers -- Customer Management$ ec customers --top 5
┌──────────────────────┬──────────┬────────┬─────────────┬─────────────┐
│ Customer │ Orders │ Total │ Last Order │ Platform │
├──────────────────────┼──────────┼────────┼─────────────┼─────────────┤
│ Tanaka Yui │ 7 │¥32,600 │ 2026-02-27 │ BASE │
│ Suzuki Kenji │ 5 │¥24,100 │ 2026-02-28 │ Both │
│ Yamada Aiko │ 5 │¥21,800 │ 2026-02-20 │ STORES │
│ Sato Hiroshi │ 4 │¥19,200 │ 2026-02-15 │ BASE │
│ Ogawa Miki │ 4 │¥16,400 │ 2026-02-22 │ STORES │
└──────────────────────┴──────────┴────────┴─────────────┴─────────────┘
Top 5 by lifetime value | Total customers: 312
ec coupons -- Coupon Management$ ec coupons create --platform base --code SPRING2026 --discount 15% --min-order 3000 --expires 2026-03-31
Coupon created on BASE.
Code: SPRING2026
Discount: 15% off
Min Order: ¥3,000
Expires: 2026-03-31
Usage Limit: Unlimited
Status: Active
ec shipping -- Shipping Management$ ec shipping update B-20260228 --carrier yamato --tracking 3456-7890-1234
Order B-20260228 shipping updated.
Carrier: Yamato Transport
Tracking: 3456-7890-1234
Status: [PAID] -> [SHIPPED]
Notification: Customer email sent to nakamura@example.com
Tracking URL: https://toi.kuronekoyamato.co.jp/cgi-bin/tneko?number=345678901234
ec bulk -- Bulk Operations$ ec bulk update-price --from-csv price_update.csv --platform base --confirm
Processing bulk price update...
┌──────────────────────────────┬───────────┬───────────┐
│ Product │ Old Price│ New Price │
├──────────────────────────────┼───────────┼───────────┤
│ Hand-dyed indigo tote bag │ ¥4,980 │ ¥5,280 │
│ Ceramic matcha bowl (wabi) │ ¥3,200 │ ¥3,500 │
│ Washi paper notebook A5 │ ¥1,200 │ ¥1,380 │
└──────────────────────────────┴───────────┴───────────┘
3 products updated on BASE | Audit logged.
ec settings -- Shop Settings$ ec settings
┌────────────┬──────────────────────────────────────────────┐
│ Platform │ Shop Details │
├────────────┼──────────────────────────────────────────────┤
│ BASE │ Shop: Wabi-Sabi Crafts │
│ │ URL: wabisabi-crafts.thebase.in │
│ │ Plan: Growth (¥5,980/mo) │
│ │ Products: 23 published, 4 draft │
│ │ Payment: Credit card, Convenience store │
├────────────┼──────────────────────────────────────────────┤
│ STORES │ Shop: Wabi-Sabi Crafts STORES │
│ │ URL: wabisabi.stores.jp │
│ │ Plan: Standard (¥2,178/mo) │
│ │ Products: 18 published, 1 draft │
│ │ Payment: Credit card, Carrier billing │
└────────────┴──────────────────────────────────────────────┘
ec sync -- Inventory Sync$ ec sync --direction base-to-stores --dry-run
Inventory Sync Preview (BASE -> STORES)
┌────────────────────────────────┬────────────┬──────────────┬───────┐
│ Product (by SKU) │ BASE Stock │ STORES Stock │ Delta │
├────────────────────────────────┼────────────┼──────────────┼───────┤
│ SKU-001 Indigo tote bag │ 12 │ 9 │ +3 │
│ SKU-002 Matcha bowl │ 8 │ 8 │ = │
│ SKU-003 Cotton t-shirt │ 45 │ 40 │ +5 │
│ SKU-005 Hinoki phone stand │ 30 │ 28 │ +2 │
└────────────────────────────────┴────────────┴──────────────┴───────┘
3 products to sync | 1 unchanged | Run without --dry-run to apply
Dual-Platform Commerce Workflow
════════════════════════════════
┌──────────────┐ ┌──────────────┐
│ BASE API │ │ STORES API │
│ (thebase.in)│ │ (stores.jp) │
└──────┬───────┘ └──────┬───────┘
│ │
└─────────────┬─────────────────────┘
▼
┌────────────────┐
│ Platform Router│
│ & Normalizer │
└───────┬────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌────────────┐ ┌─────────┐ ┌──────────┐
│ Products │ │ Orders │ │Inventory │
│ Module │ │ Module │ │ Sync │
└─────┬──────┘ └────┬────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────┐
│ Analytics Engine │
│ Revenue | AOV | Trends | Rankings │
└──────────────────┬──────────────────┘
▼
┌─────────────────────────────────────┐
│ Export: CSV(SJIS) | JSON | TSV │
│ Reports: Daily | Weekly | Monthly │
└─────────────────────────────────────┘
| Error | Cause | Solution |
|---|---|---|
BASE_AUTH_EXPIRED: Token expired | BASE OAuth access token has expired (60-day lifetime). | Run ec auth refresh --platform base to use the refresh token, or re-authorize via OAuth flow. |
STORES_401: Unauthorized | STORES access token is invalid or revoked. | Generate a new token in STORES dashboard > Settings > API and update STORES_ACCESS_TOKEN. |
SYNC_SKU_MISMATCH: 3 unmatched SKUs | Product SKUs differ between BASE and STORES. | Run ec sync --show-unmatched to see mismatches, then create a mapping file at ~/.ec-agent/sku-map.json. |
RATE_LIMIT: BASE 30/min exceeded | Too many BASE API calls in a single minute. | Reduce batch size or wait 60 seconds. The agent queues excess calls automatically. |
CSV_ENCODING: Invalid Shift-JIS | CSV file contains characters outside Shift-JIS range. | Use --encoding utf8 flag or convert the file to UTF-8 before importing. |
PRICE_INVALID: Negative price | A bulk update CSV contains a negative or zero price. | Fix the CSV and re-run. Prices must be positive integers in JPY. |
STOCK_NEGATIVE: Cannot set stock below 0 | Inventory sync would result in negative stock on target platform. | Use --floor 0 flag to set minimum stock to zero instead of applying the negative delta. |
1. Do I need both BASE and STORES accounts? No. You can use the agent with just one platform. Configure only the tokens for the platform you use.
2. How does cross-platform inventory sync work?
The agent matches products by SKU across platforms. When stock changes on one platform, ec sync calculates the delta and pushes it to the other.
3. Can I import products from a CSV?
Yes. Use ec bulk import --from-csv products.csv --platform base. The CSV should include: title, price, stock, description, image_url.
4. Are prices always in JPY? By default, yes. Both BASE and STORES primarily operate in JPY. The agent displays all prices with yen formatting.
5. How do I handle Shift-JIS CSV exports?
The agent auto-detects encoding. For explicit control, use --encoding shift-jis or --encoding utf8 on any export/import command.
6. Can I manage multiple BASE shops?
Yes. Use --shop <shop-id> to target a specific shop, or configure multiple shops in ~/.ec-agent/config.yaml.
7. What carriers are supported for shipping? Yamato Transport, Sagawa Express, and Japan Post (Yu-Pack) are natively supported with auto-formatted tracking URLs.
8. Is there a sandbox/test mode?
Use --dry-run on any write operation to preview changes without applying them. BASE also offers a sandbox API environment.
9. How often should I sync inventory?
For active shops, every 15-30 minutes is recommended. Set up a cron job: */15 * * * * ec sync --direction bidirectional --auto.
10. Can I generate tax-inclusive prices?
Yes. Use ec bulk tax-adjust --rate 10 --platform base to recalculate prices with Japan's 10% consumption tax included.
11. Does the agent handle digital products?
Yes. Both BASE and STORES support digital downloads. Use ec products create --type digital --file ./ebook.pdf.
12. How do I track conversion rates?
Use ec analytics --detailed to see visitor-to-order conversion rates (requires Google Analytics integration for traffic data).
| Location | Purpose | Retention |
|---|---|---|
~/.ec-agent/config.yaml | API tokens, shop IDs, preferences | Persistent |
~/.ec-agent/inventory.db | SQLite database for inventory tracking | Persistent, pruned monthly |
~/.ec-agent/sync-log.json | Inventory sync history with deltas | Rolling 90 days |
~/.ec-agent/analytics-cache/ | Cached order and revenue data | 10-minute TTL |
~/.ec-agent/exports/ | Generated CSV/JSON/TSV files | User-managed |
~/.ec-agent/sku-map.json | Cross-platform SKU mapping | Persistent |
~/.ec-agent/audit.log | Destructive operation log | Rolling 30 days, max 10MB |
All data is stored locally. API tokens are stored in the config file; use environment variables for enhanced security. The SQLite inventory database can be backed up with standard file copy.
| Feature | BASE & STORES Agent | BASE Web Dashboard | STORES Web Dashboard | Shopify CLI |
|---|---|---|---|---|
| Unified multi-platform | Both in one CLI | BASE only | STORES only | Shopify only |
| Bulk product operations | CSV import/export | Limited (50 items) | Manual only | Theme-focused |
| Inventory sync | Cross-platform | Single shop | Single shop | N/A |
| Japanese-native | Full (SJIS + UTF-8) | Yes | Yes | Partial |
| Sales analytics (CLI) | Combined reports | Web dashboard | Web dashboard | Partner API |
| Carrier integration | Yamato/Sagawa/JP Post | Yamato/Sagawa | Basic | Multi-carrier |
| Coupon management | Full CRUD | Web UI | Web UI | Scripts |
| Offline product view | Cached locally | No | No | No |
| Export formats | CSV(SJIS), JSON, TSV | CSV | CSV | JSON |
| Setup time | 3 minutes | Browser | Browser | 15 minutes |
| Price | Free (OSS) | Platform fees | Platform fees | $25+/mo |
| API rate handling | Auto-queue + backoff | N/A | N/A | Manual |
BASE & STORES Agent -- two platforms, one terminal, zero browser tabs.