OSS (One-Stop-Shop)

Paid pluginsize Lplanned, not built

Indicative price, not an offer: €59/mo; monthly OSS reporting ready-to-file for France, Germany, Netherlands, etc.

Generated from docs/plan/paid/oss/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid service maintaining accurate VAT rules for EU One-Stop-Shop (OSS) filing, generating monthly reports ready to file with each member state’s tax authority, and ensuring merchants never miss deadlines or submit incorrect sales data.

The problem

A Swedish merchant sells to 15 EU countries. Each quarter, she must file OSS returns (distance-selling VAT) to each country’s tax authority in that country’s format. France wants CSV, Germany wants XML. She’s never filed correctly—always misses one country or uses wrong format—and faces fines. She pays an accountant €5k/year to handle this, but filing is still error-prone.

What it does

• Master VAT rates per country (maintained as part of eu-tax-compliance-pack)
• Monthly sales aggregation by destination country (sum total, no line items)
• OSS filing-ready export: per-country format (CSV, XML, PDF as required)
• Filing deadline tracking: alerts merchant 10 days before deadline for each country
• Compliance dashboard: shows countries where filing is due, filing status (not filed/filed/accepted/rejected)
• Support: pre-filled filing forms where applicable, guided upload to tax authority (where available)
• Audit trail: which export version was sent, when, to which country
• Multi-currency handling: orders in different currencies are converted to shop currency for reporting
• Threshold tracking: alerts merchant if sales exceed country-specific OSS thresholds (e.g., €35k/year for micro-businesses)

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.

• Submitting files directly to tax authorities (merchant or accountant owns the filing action)
• Processing country responses (e.g., if Germany rejects a filing, we don’t auto-resubmit)
• Goods/services classification (‘is this product standard-rate or reduced?’)—merchant responsibility
• Reverse-charge or B2B VAT—handled separately (reverse-charge slug)
• Non-EU distance selling (UK, Switzerland, Norway)

Data model

Extends destination-based-tax with: OSSReport(shopId, period, country, sales_minor, report_format, export_date, status); OSSThreshold(countryCode, threshold_amount, period_type). Both stored in plugin/settings, no schema migration to core.

API

• GET /oss/report/:year/:month — return sales by country
• POST /oss/export/:country/:period — generate country-specific file (CSV/XML/PDF)
• GET /oss/deadlines — list upcoming filing deadlines
• GET /oss/status — filing status for each country (not filed/filed/accepted)
• POST /oss/mark-filed/:country/:period — mark as filed (merchant confirms after uploading)

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

Admin

OSS compliance hub: calendar showing filing deadlines, monthly sales by country (sortable, filterable), export button for each country, status tracker (red=not filed, yellow=filed waiting acceptance, green=accepted), threshold alerts, audit log

The seam — why this is paid

Core owns: order storage, tax line items, currency handling. Paid pack owns: OSS rule maintenance per country, filing-ready export generation, deadline tracking, support for edge cases.

Per-country obligation: we maintain OSS rules per EU member state, file-ready reports

Dependencies

• eu-tax-compliance-pack (VAT rates must be accurate)
• destination-based-tax (tax lines must be calculated)
• order schema (order.destination_country required)

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.

• A monthly report for January 2025 shows sales to Germany €50k, France €30k, Spain €25k (summed across all orders, no line items)
• Export for Germany returns CSV with columns: country, period, tax_amount, sales_amount (ready to paste into German tax form)
• Export for France returns XML in valid French format (schema can be validated against DGFIP spec)
• A merchant is alerted 10 days before the last day of month to file (e.g., Feb 20 alert for Feb 28 deadline)
• If sales to Ireland exceed €35k threshold, merchant receives alert ‘OSS threshold exceeded for Ireland’
• Filing deadline list shows all 27 countries (even if €0 sales) and all relevant deadlines
• Marking a report as ‘filed’ creates an audit log entry (date, period, country, export version)
• If a country’s filing format changes (e.g., new CSV version), next month’s export uses new format

Risks

If OSS rules are incorrect, all merchants file wrong numbers and face fines—this is a high-liability service. Deadline miscalculation: if we alert 9 days instead of 10, merchant misses deadline. Multi-country simultaneous filings during month-end can overwhelm support. Currency conversion bugs: if order currency != shop currency, conversion must be exact and auditable.

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.