TECHNICAL DOCUMENTATION

FreshGuard AI — Developer Docs

Everything you need to know about how FreshGuard AI works under the hood — data storage, webhooks, API, and CSV format.

🏗️

Architecture Overview

FreshGuard AI is a Shopify-embedded app built with React Router v7 and @shopify/shopify-app-react-router. It uses Shopify Metaobjects as its primary datastore, meaning all your batch data lives directly on Shopify's infrastructure — not on a third-party server. This gives you:

Zero data loss risk — data is as safe as your Shopify store itself.
No sync lag — reads and writes happen directly via Shopify's Admin GraphQL API.
GDPR compliance by default — data deletion is handled by Shopify's mandatory privacy webhooks.

Data Flow:

Shopify order → orders/create webhook → FreshGuard FEFO engine → Metaobject update → Order tag + metafield write

🗂️

Metaobject Schema

Each inventory batch is stored as a Shopify Metaobject of type $app:inventory_batch. The schema fields are:

Field Key	Type	Description	Required
batch_number	single_line_text_field	Unique lot/batch identifier (e.g. LOT-2026A)	✅
expiry_date	date	Expiry date in ISO format (YYYY-MM-DD)	✅
initial_quantity	number_integer	Stock quantity when the batch was first created	✅
current_quantity	number_integer	Current remaining stock (decremented by FEFO)	✅
batch_status	single_line_text_field	Active \| Out of stock \| Expired	✅
location_id	single_line_text_field	Shopify Location GID for multi-location tracking
barcode	single_line_text_field	Standard barcode string
gtin	single_line_text_field	GS1 GTIN barcode for industry compliance
invoice_number	single_line_text_field	Supplier invoice or reference number
cost_per_unit	number_decimal	Unit cost for financial analytics and wastage
supplier	single_line_text_field	Supplier or vendor name

Batch-to-variant association is stored as a JSON array in a productVariant.metafield(namespace: "$app:inventory", key: "batches_data") field.

📄

CSV Import / Export Format

Use the bulk CSV feature in the Batches tab → Import or Analytics → Export. The file must use these exact column headers:

Column Name	Format / Example	Required?
sku	STRING — e.g. APPLE-RED-001	✅ for import
batch_number	STRING — e.g. LOT-2026A	✅
expiry_date	DATE — YYYY-MM-DD (e.g. 2026-09-30)	✅
initial_quantity	INTEGER — e.g. 500	✅
current_quantity	INTEGER — e.g. 320	✅
batch_status	Active \| Out of stock \| Expired	✅
barcode	STRING — optional barcode value
gtin	STRING — GS1 GTIN (e.g. 00012345678905)
cost_per_unit	DECIMAL — e.g. 2.50
location_id	Shopify Location GID
invoice_number	STRING — e.g. INV-2024-0012
supplier	STRING — e.g. FreshFoods Ltd.

🔗

Webhooks & Automation

FreshGuard subscribes to the following Shopify webhooks automatically upon installation:

orders/create

Triggers FEFO engine. Deducts batch quantities, tags the order with the Batch Number, and writes the consumed_batches metafield for traceability.

app/uninstalled

Triggers automatic deletion of all session data and store configuration from FreshGuard's database within 48 hours.

shop/redact (GDPR)

Triggers full erasure of all store data from FreshGuard systems, as required by Shopify's GDPR compliance.

customers/redact (GDPR)

Triggers erasure of any identifiable customer data FreshGuard may hold.

customers/data_request (GDPR)

Provides any customer data FreshGuard holds upon request.

⚙️

App Proxy API Endpoint

FreshGuard exposes a public JSON endpoint via Shopify's App Proxy at /apps/freshguard/expiry. This endpoint is callable from Liquid themes and JavaScript without authentication.

REQUEST

GET /apps/freshguard/expiry?variant_id={shopify_variant_id}

RESPONSE (200 OK)

{
  "expiry_date": "2026-09-30",
  "batch_number": "LOT-2026A",
  "days_remaining": 113,
  "is_expiring_soon": false
}

💳

Billing & Plan Limits

Free

$0/month

Up to 15 tracked product variants
1,000 FEFO order deductions/month
Unlimited batches per product
Multiple store locations
Batch History & Audit Log
Recall Report
Email notifications
CSV Export
Email support

Pro

$9.00/month

Unlimited tracked products
Unlimited order deductions
Financial Analytics dashboard
Value at Risk & Wastage reporting
Automated Discount Sync
Expiration Value Forecast
Automated Product Tagging
Storefront Expiry Display
Packing Slip integration
Priority support
7-day free trial

📋

Batch History & Audit Log

Every batch event is stored as a JSON array in a shop-level metafield at namespace $app:settings, key batch_history. The array is capped at the most recent 500 events to stay within Shopify's metafield size limits.

Each event object contains: { batchNumber, action, quantityChange, orderId, timestamp, note }. Action types: batch_created, batch_deducted, batch_expired, batch_updated.

🚨

Recall Report & Compliance

The Recall Report cross-references the consumed_batches order metafield (written by the FEFO webhook) against all Shopify orders. Given a batch number, it returns a list of orders containing that batch, including: Order ID, Customer Name, Customer Email, Order Date, and Quantity Consumed. The result can be exported as a CSV for food safety and regulatory outreach. This feature requires FEFO order tagging to have been active when orders were placed.

← Feature Guides FAQ →