Quickstart: Your Commerce Engine
Connect payments, enable fraud detection, configure inventory, launch products, pair POS hardware, and wire abandoned-cart recovery — the full setup in 6 steps, in under 25 minutes.
Connect Payment Gateways
| Provider | Best for | Notes |
|---|---|---|
| **Stripe** | Default — broadest coverage, easiest setup | 135+ currencies, 195+ countries |
| **Adyen** | Enterprise — best for multi-region + complex compliance | Higher minimums, deeper analytics |
| **PayPal** | Consumer-favorite checkout option | Side-by-side with card gateways |
| **Square** | Brick-and-mortar + integrated POS hardware | US + Canada + Australia + UK |
| **Razorpay** | India-first + Southeast Asia footprint | UPI, netbanking, regional methods |
| **Manual** | Invoice / bank-wire / offline gateways | For enterprise invoice billing flows |
Configure Fraud Detection
| Score range | Default action | Override possible |
|---|---|---|
| 0–30 | Auto-approve | Yes |
| 31–70 | Manual review queue | Auto-approve with override |
| 71–100 | Block + alert | Manual override + audit log |
Set Up Multi-Location Inventory
Create warehouses + retail locations in Commerce → Inventory → Locations. Each location owns its own stock count + safety stock buffer.
Atomic inventory locks prevent double-sells at scale. When an order reserves stock, Aeion acquires a FOR UPDATE row-level lock in PostgreSQL. At 10,000+ orders/hour during a flash sale, zero overselling.
Multi-location routing options:
- Closest to customer — Haversine distance, route to nearest warehouse with stock
- Cheapest shipping — calculate carrier rates per warehouse, pick the lowest
- Split shipments — if no single location has all items, automatically split across warehouses
- Preferred location — manual override for compliance / dropship arrangements
typescript
// Multi-location routing strategy lives on the store config — patch the stores collection
await aeion.api.patch(/v1/commerce_stores/${storeId}, {
fulfillmentRouting: "closest-to-customer",
splitShipments: true,
safetyStockPercent: 5, // Reserve 5% of stock per location
reorderTrigger: { atOrBelow: 10, generatePoDraft: true },
});
Launch Your First Product
Navigate to Commerce → Products and click New Product. Product configuration:
- Variants — size, color, material combinations (auto-generates variant SKUs)
- Pricing — per-variant + per-customer-tier overrides (B2B wholesale ready)
- Images — drag-drop, auto-crop, CDN-served via Aeion Media
- Inventory — per-variant + per-location tracking
- Tax classes — assigned by category for automatic tax calculation
- Shipping rules — weight, dimensions, hazmat flags
- SEO — meta title/description/OG image (AI-optimized in Content module)
- Related products — cross-sells + upsells on PDP
Subscription products — set a recurring schedule (weekly/monthly/annual), enable add/remove items per cycle, configure swap/skip/pause customer flows.
B2B wholesale tiers — separate price list per customer segment ("Bronze", "Silver", "Gold"). Net-15/30/60 payment terms, minimum order quantities, gated portal access.
Set Up POS Hardware
| Device type | Supported brands |
|---|---|
| Receipt printer (ESC/POS) | Star Micronics, Epson TM-series, Bixolon, Citizen |
| Cash drawer | Generic 12/24V over RJ-11 |
| Barcode scanner | Honeywell, Zebra, Datalogic — HID + USB-COM |
| Card reader | Stripe Terminal (BBPOS, Verifone), Adyen, Square hardware |
| Customer display | LED + LCD line displays, dual-monitor mode |
| Weight scale | Mettler Toledo, Avery Berkel, Cardinal |
| Label printer | Zebra ZD-series, Brother QL-series |
Wire Abandoned-Cart Recovery
| Step | Trigger | Action | Conversion lift |
|---|---|---|---|
| 1 | 1h after abandon | Email reminder, no discount | 5-10% |
| 2 | 24h after abandon | Email + SMS, $5 discount auto-generated | 10-15% |
| 3 | 72h after abandon | Final email, larger discount + free shipping | 5-8% |
Integration Recipes
CRM auto-create on first purchase. When a new email completes checkout, a CRM contact record is created automatically with name, email, order history, and LTV. Marketing campaigns can target them immediately.
Finance GL posting. Every order, refund, and adjustment posts to the Aeion Finance general ledger in real-time — no nightly batch reconciliation. Tax, fees, gateway charges all line-itemed.
Marketing campaigns by purchase pattern. Marketing module subscribes to commerce.order.completed and segments customers automatically ("first-time buyer", "repeat customer", "lapsed > 90 days"). Trigger personalized email sequences without manual setup.
Loyalty stacking at checkout. Loyalty-tier discounts (Gold = 10% off) stack with promotional codes (SPRING20 = 20% off) via configurable precedence rules (additive 30% or multiplicative 28%).
Fulfillment routing. Orders flow to the Fulfillment module with allocation, pick lists, and carrier integration. Last-mile via the Fleet module if you operate your own drivers.
B2B wholesale portal. Same product catalog, different pricing + payment terms per customer tier. Gated portal with tier-specific catalog, net-15/30/60 invoicing, and bulk-order pricing.
Troubleshooting
Order shows as "stuck pending". Usually means payment was captured but the order didn't finish being created, or payment failed silently. Check the order's audit timeline in Admin → Orders → Activity. Common cause: webhook from payment gateway didn't arrive (check gateway dashboard). A reconciliation job runs every 5 minutes to auto-fix orphaned charges.
Fraud detection blocking legitimate orders. Lower the score thresholds (Admin → Fraud Settings). Add the customer's IP to your allowlist if they're a regular. Audit-log the override so you can identify false-positive patterns and tune rules.
Inventory count drift between locations and orders. Run the inventory reconciliation tool (Admin → Inventory → Reconcile). It compares Aeion's count against an external source (physical scan / 3PL feed). Common causes: returns processed but not received, or external WMS systems updating stock outside Aeion.
Abandoned cart emails not sending. Check the Customer's preferences — they may have opted out. Verify email gateway is configured (Admin → Notifications → Email). Test the recovery URL manually: /checkout?recover={token} should restore the cart.
POS hardware not detected. Bridge needs the corresponding driver installed. Check Admin → Bridge → Devices. For USB devices: verify USB pass-through is enabled on the Bridge box. For network devices (printer over Ethernet): ping the device IP from the Bridge host.
Multi-location split-shipment ratios are off. Configurable in Admin → Fulfillment → Routing → Split Logic. Default: minimize package count. Switch to "minimize shipping cost" or "single-warehouse-preferred" depending on your business priority.
Frequently Asked Questions
When an order reserves stock, Aeion acquires a `FOR UPDATE` row-level lock on the product row in PostgreSQL. No other concurrent transaction can read or modify that row until the lock releases. If the lock cannot be acquired within 5 seconds, the request times out cleanly. Zero double-sells even at 10,000+ orders/hour during flash sales.
Checkout API returns 403 with `FRAUD_BLOCKED`. Order is not created, payment not processed, customer sees a generic "cannot be processed" message. Flagged orders log to the manual-review queue. Admin can override + audit log captures who/why.
Each abandoned cart gets a cryptographically random 64-char token. Recovery URLs use `/checkout?recover={token}` for stateless restoration. The 24h step auto-generates a single-use discount code tied to the specific cart.
Yes. Create customer tiers ("Wholesale", "VIP") and assign price lists with min-order quantities. Wholesale customers log into a gated portal with tier pricing pre-applied. Net-15/30/60 terms supported.
Pricing, tax, and discount rules compile to Wasm and deploy to Bridge. Transactions process locally at sub-10ms. Queued and synced on reconnection with conflict resolution for edge cases.
Yes. Aeion's revenue model is a flat monthly rate, not per-transaction. 100% of every sale flows to your merchant account (after gateway's own fees — Stripe/Adyen's published rates, not Aeion's). No revenue share.
Yes. Configure primary + fallback. Per-region routing also supported (Stripe for US, Adyen for EU). Customer-facing experience is identical; backend fallback transparent.
Admin → Orders → Refund. Full or partial. Refund flows back through the original payment method. GL posts the reversal automatically. If the order had a discount + loyalty points, both are adjusted/clawback per your policy.
First-class subscription engine. Recurring schedules, upgrades/downgrades, proration, dunning (configurable retry schedule), pause/swap/skip flows, and metered billing all supported. Stripe Billing API used under the hood for the gateway-side schedule.
No hard limit. Production customers run catalogs of 5M+ SKUs with no perf degradation. PostgreSQL's GIN indexes + the federated Aeion Search backbone keep search sub-100ms even at scale.