JSON Export

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/json-export/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merchants export their entire AstroBaaS data (products, customers, orders, settings) as JSON files for archival, analysis, or migration. Export is point-in-time; merchant can schedule regular exports or run on-demand. JSON format is fully documented and portable. Core owns the export logic; this is infrastructure, not a paid feature.

The problem

Merchants are locked into AstroBaaS with no way to export their data. If they want to switch platforms, data portability is essential. JSON export provides a machine-readable archive.

What it does

• Full export: all products, customers, orders, settings exported to JSON
• Partial export: admin can exclude categories (e.g., export products only, skip orders)
• File structure: export is a ZIP with separate JSON files per entity type
• Pagination: large exports are split into multiple files (e.g., customers-1.json, customers-2.json)
• Timestamps: each export is dated (export-2026-09-03-14-30.zip)
• Schema documentation: export includes JSON schema file for third-party tools
• Scheduled exports: admin can schedule weekly exports
• Download history: admin sees all past exports, can re-download

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Real-time exports: export is point-in-time only (no streaming data).
• Filtered exports: we export all data; filtering is merchant’s responsibility after download.
• Format conversion: we provide JSON only; CSV/Excel conversion is separate feature (csv-export).

Data model

New document: export_record { exportId, timestamp, includeProducts, includeCustomers, includeOrders, includeSettings, fileSize, status (completed, failed) }.

API

• POST /api/export/json/start { includeProducts, includeCustomers, includeOrders, includeSettings } -> { exportId }
• GET /api/export/json/{exportId}/status -> { status, progress, fileSize }
• GET /api/export/json/{exportId}/download -> ZIP file
• GET /api/export/json/history (admin only) -> list of past exports
• GET /api/export/json/schema -> JSON schema document

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin sees: export builder (toggle checkboxes for products, customers, orders, settings), export history with dates and file sizes, download links, scheduled export settings.

The seam — why this is core

Core owns JSON export logic and format. No paid seam; this is infrastructure.

Core owns the interface + honest JSON serializer; data portability is infrastructure, not a per-country obligation or credential.

Dependencies

• product subsystem (existing)
• customer subsystem (existing)
• order subsystem (existing)
• settings subsystem (existing)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Admin clicks ‘Export’, selects all checkboxes, clicks ‘Start’; export completes in 2 minutes
• ZIP file contains products.json (1000 items), customers.json (500 items), orders.json (2000 items)
• Each JSON file is valid JSON, parseable by third-party tools
• JSON schema file (schema.json) documents all fields and types
• Admin can schedule weekly exports; exports run every Sunday at midnight
• Export history shows 5 past exports with dates and file sizes; admin can re-download any
• A 50 MB export is split into multiple files (orders-1.json, orders-2.json, etc.)

Risks

If JSON contains PII (customer emails, phone numbers) unencrypted, data leak is possible when exported. If schema is wrong or undocumented, third-party tools cannot parse export correctly. If export includes deleted products (soft-deleted), merchant is confused by stale data. If export is too large (>1 GB), download fails or times out (file size limit not enforced). If timestamp is not included, merchant doesn’t know export age.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.