## ⚡ FlashLock: The Atomic Inventory Engine #### **Stop overselling. Block inventory bots. Automate complex bundles.** FlashLock is a high-performance Inventory Middleware API designed for high-growth merchants, Headless stores (Next.js/Hydrogen), Shopify, Woocommerce, Amazon etc and multi-channel sellers. Standard e-commerce platforms (Shopify, WooCommerce) suffer from latency—they update too slowly during high-traffic events. FlashLock acts as a "Traffic Cop" sitting in front of your store, enforcing Atomic Locking to guarantee that you never sell stock you don't have. #### 🚀 Key Features *Why developers choose FlashLock over standard databases:* ##### 1. 🛡️ Guaranteed Overselling Protection (Atomic Locks) Eliminate race conditions. If 1,000 customers try to buy the last item at the exact same millisecond, FlashLock ensures only one succeeds. Perfect for "Hype Drops" and Flash Sales. ##### 2. 📦 Intelligent Product Bundling API Solve the logistics nightmare of "Kitting." Define a Bundle (e.g., "Gift Set" = 1 Shirt + 1 Hat). When a user locks the Set, FlashLock automatically locks the individual components. If any component is out of stock, the Bundle is instantly marked unavailable. ##### 3. 📜 Full Inventory Audit Ledger *("Who moved my stock?")* Every single action—lock, sale, restock, or expiration—is recorded in an immutable history log. access via API (`GET /inventory/:sku/history`) to track inventory movement down to the second. ##### 4. 🧹 Auto-Janitor (Cart Expiry) Never lose sales to "zombie carts." If a customer adds an item to their cart but abandons it, FlashLock automatically releases the stock back to the shelf after the TTL expires. ##### 5. 🤖 High-Velocity Bot Defense Don't let scalper bots hoard your inventory. FlashLock monitors request velocity in real-time. If a traffic spike is detected, it automatically switches to "Panic Mode," reducing cart reservation times from 15 minutes to 2 minutes to force rapid checkout and baffle bots. ##### 6. 📉 Virtual Inventory & Backorders Capture revenue even when the warehouse is empty. Enable is_backorderable on specific SKUs. Allow customers to lock and buy into negative inventory while maintaining a precise ledger of what is owed. ##### 7. 🔔 Low-Stock Webhooks (Push Notifications) Stop polling. FlashLock proactively notifies your backend or ERP via Webhooks the moment an item's stock drops below your defined safety_stock threshold. Automate your reordering process. ##### 8. 🌍 Multi-Location Support Manage inventory across multiple warehouses (e.g., "NY-Main," "London-Hub") with a single API call. #### 💔 Why Existing Solutions Fail (The Pain Points) Most developers try to solve inventory sync using standard tools, but they eventually hit a wall. Here is why the standard stack breaks under pressure: ##### 1. Native Platforms (Shopify, WooCommerce, Magento) - ###### ❌ Eventual Consistency: These platforms are designed for browsing, not high-frequency trading. During a traffic spike, their database updates are too slow, leading to "Phantom Inventory" (showing stock that is already sold). - ###### ❌ Reactive, Not Proactive: They usually deduct stock after payment. This leads to the "Cart Heartbreak" scenario where a user fills their details only to be told "Out of Stock" at the final click. - ###### ❌ Strict Rate Limiting: If you try to update 5,000 SKUs instantly via their API, you will hit rate limits (e.g., Shopify’s leaky bucket), causing sync delays of 10+ minutes. ##### 2. Automation Tools (Zapier, Make, n8n) - ###### ❌ The "Race Condition" Trap: These tools are Event-Based, not State-Aware. By the time Zapier receives a "Order Created" webhook and triggers an update, 5 other people have already bought the item on another channel. - ###### ❌ No Rollback Logic: If an inventory update fails halfway through a workflow, there is no automatic way to revert the stock, leaving your stores out of sync. - ###### ❌ Cost at Scale: Paying per-task for inventory checks becomes prohibitively expensive during high-volume months. ##### 3. Enterprise ERPs (NetSuite, SAP, Oracle) - ###### ❌ The "Sync Gap": ERPs are systems of record, not real-time transaction engines. Most sync with the storefront every 15 to 60 minutes. This "Blind Window" is where 90% of overselling happens. - ###### ❌ Slow API Response: ERP APIs are notoriously heavy and slow (500ms+ latency), making them unsuitable for real-time "Add to Cart" checks. ##### 4. Custom/Headless Databases (Redis/Postgres alone) - ###### ❌ High Maintenance: Building your own locking logic requires managing race conditions, concurrency, and connections manually. - ###### ❌ No Bot Defense: A standard database doesn't know the difference between a human and a scalper bot, allowing scripts to lock 100% of your stock in milliseconds. #### 🟢 The FlashLock Advantage FlashLock replaces these fragile patchworks with a dedicated State Engine. - ###### vs. Ecommerce: We lock before checkout. - ###### vs. Zapier: We allow atomic transactions (all or nothing). - ###### vs. ERPs: We respond in <50ms. - ###### vs. Custom: We include built-in Bot Defense and Bundle Logic. #### 💡 Use Cases ##### High-Velocity Retail & Drops - ###### Product Drops: Prevent overselling when 50,000 users hit "Buy" simultaneously. - ###### Black Friday/Cyber Monday: Offload high-concurrency database writes from your main e-commerce platform. - ###### Flash Sales: Enforce strict inventory limits for time-sensitive promotions. ##### Logistics & Complex Products - ###### Subscription Boxes (Kitting): Automatically lock component SKUs (e.g., Lipstick + Liner) when a parent Bundle is added to the cart. - ###### "Build-Your-Own" Configuators: Lock individual PC parts or furniture components in real-time as users customize products. - ###### Gift Sets: Ensure you never sell a gift basket if one item inside is out of stock. ##### Omnichannel & Physical Retail - ###### BOPIS (Buy Online, Pickup In-Store): Reserve stock specifically at a local retail branch to prevent walk-in customers from buying sold items. - ###### POS Integration: Sync iPad/Square POS systems with your online store in real-time. - ###### Multi-Warehouse Routing: Manage stock across "East Coast," "West Coast," and "Europe" hubs independently. ##### Pre-Sales & Crowdfunding - ###### Pre-Orders/Backorders: Capture revenue for incoming stock using Virtual Inventory (is_backorderable) while maintaining a precise debt ledger. - ###### Crowdfunding Tiers: Enforce strict limits on "Early Bird" reward tiers. ##### Emerging Tech & Platforms - ###### Live Shopping (TikTok/Instagram): Use FlashLock as the high-speed ledger for comment-based purchasing bots. - ###### NFT/Ticket Minting: Prevent double-booking of seats or limited-edition digital assets during a minting window. ##### 🛠️ Technical Specs & Authentication Format: REST / JSON Latency: <50ms Global Response Time Authentication: via RapidAPI Headers

1. Authentication

FlashLock is hosted on RapidAPI. You must include these headers in every request.

Header	Value	Description
`X-RapidAPI-Key`	(Your Key)	Provided by RapidAPI upon subscription.
`X-RapidAPI-Host`	(Host URL)	E.g., `flashlock-api.p.rapidapi.com`

2. Configuration & Setup

Set up your warehouses, product bundles, and alert webhooks.

POST /api/v1/locations

Parameter	Type	Required	Description
`id`	String	Yes	Unique ID (e.g., "NY-MAIN"). No spaces.
`name`	String	Yes	Human readable name.

Request Body

{
  "id": "NY-MAIN",
  "name": "New York Distribution Center"
}

Response (200 OK)

{
  "status": "created",
  "location_id": "NY-MAIN"
}

GET /api/v1/locations

Get a list of all registered locations.

Response (200 OK)

[
  {
    "id": "default",
    "name": "Main Warehouse"
  },
  {
    "id": "NY-MAIN",
    "name": "New York Distribution Center"
  }
]

POST /api/v1/bundles

Define a "Kit" or "Bundle". Locking the parent SKU will automatically lock the child components.

Parameter	Type	Required	Description
`parent_sku`	String	Yes	The SKU of the Bundle/Set.
`components`	Array	Yes	List of items inside the bundle.
`components[].sku`	String	Yes	SKU of the physical item.
`components[].quantity`	Integer	Yes	Qty needed per bundle.

Request Body

{
  "parent_sku": "SUMMER-GIFT-SET",
  "components": [
    { "sku": "SHIRT-L", "quantity": 1 },
    { "sku": "HAT-RED", "quantity": 1 }
  ]
}

Response (200 OK)

{ "status": "bundle_created" }

GET /api/v1/bundles/:sku

Retrieve the recipe for a specific bundle SKU.

Response (200 OK)

[
  { "sku": "SHIRT-L", "quantity": 1 },
  { "sku": "HAT-RED", "quantity": 1 }
]

POST /api/v1/config/webhook

Set a URL to receive POST alerts when stock drops below safety levels.

Parameter	Type	Required	Description
`url`	String	Yes	Your HTTPS endpoint.

Request Body

{ "url": "https://your-store.com/webhooks/low-stock" }

Response (200 OK)

{ "status": "webhook_set", "url": "..." }

GET /api/v1/config/webhook

View currently configured webhook URL.

Response (200 OK)

{ "url": "https://your-store.com/webhooks/low-stock" }

Webhook Payload

If you configure a webhook, FlashLock will send this JSON payload to your server when stock drops below the safety threshold.

Incoming POST Request

{
  "event": "LOW_STOCK",
  "sku": "NIKE-AIR-JORDAN-1",
  "remaining": 4,
  "timestamp": "2025-12-31T12:30:45Z"
}

3. Inventory Actions (Write)

The core transactional endpoints. Use these to Sync, Lock, and Sell.

POST /api/v1/inventory/sync

Initialize or overwrite physical stock levels (Admin/ERP action).

Parameter	Type	Required	Description
`sku`	String	Yes	Product Identifier.
`quantity`	Integer	Yes	Total Physical Count.
`location_id`	String	No	Target Warehouse (default: "default").
`safety_stock`	Integer	No	Buffer. Locks fail if Available <= Safety.
`is_backorderable`	Boolean	No	Allow locking negative inventory?

Request Body

{
  "sku": "NIKE-AIR-1",
  "quantity": 100,
  "location_id": "NY-MAIN",
  "safety_stock": 5,
  "is_backorderable": false
}

Response (200 OK)

{
  "status": "updated",
  "sku": "NIKE-AIR-1",
  "location": "NY-MAIN"
}

POST /api/v1/inventory/lock

Reserve stock (Add to Cart). Supports Bundles & Backorders. Atomic Operation.

Parameter	Type	Required	Description
`sku`	String	Yes	Product/Bundle to lock.
`quantity`	Integer	Yes	Amount to reserve.
`location_id`	String	No	Source Warehouse.

Request Body

{
  "sku": "NIKE-AIR-1",
  "quantity": 1,
  "location_id": "NY-MAIN"
}

Response (200 OK)

{
  "lock_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "expires_at": "2025-12-31T12:15:00Z",
  "bundle_targets": 1
}

Error: Oversold (409)

{ "error": "Oversold", "failed_sku": "NIKE-AIR-1" }

POST /api/v1/inventory/commit

Finalize sale. Permanently deducts stock associated with a Lock ID.

Parameter	Type	Required	Description
`lock_id`	UUID	Yes	The ID returned from /lock.

Request Body

{ "lock_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11" }

Response (200 OK)

{ "status": "sold", "items_processed": 1 }

4. Read Data

Query the state of your inventory for dashboards or debugging.

GET /api/v1/inventory/:sku

Get real-time stock details for a specific SKU across all locations.

Response (200 OK)

[
  {
    "location_id": "NY-MAIN",
    "sku": "NIKE-AIR-1",
    "total_qty": 100,
    "reserved_qty": 2,
    "available_qty": 98,
    "safety_stock": 5,
    "updated_at": "2025-12-31T10:00:00Z"
  }
]

GET /api/v1/locks

List all active items currently sitting in carts.

Query Param	Default	Description
`limit`	20	Pagination limit.
`offset`	0	Pagination offset.

Response (200 OK)

[
  {
    "lock_id": "a0eebc99...",
    "location_id": "NY-MAIN",
    "sku": "NIKE-AIR-1",
    "qty": 1,
    "expires_at": "2025-12-31T12:15:00Z"
  }
]

GET /api/v1/inventory/:sku/history

Get the audit ledger (Logs) for a specific item.

Query Param	Default	Description
`limit`	50	Pagination limit.
`offset`	0	Pagination offset.

Response (200 OK)

[
  {
    "event_type": "SALE",
    "change_qty": -1,
    "reason": "Committed",
    "created_at": "2025-12-31T12:10:00Z"
  },
  {
    "event_type": "LOCK",
    "change_qty": 1,
    "reason": "Cart Add",
    "created_at": "2025-12-31T12:05:00Z"
  }
]