Documentation

Fruga integration docs

A technical guide to the platform: connecting stores, integrating mobile apps, publishing your own applications, and the REST API.

Platform Overview

FrugalDomain is a platform that centralizes catalog, inventory, content, and order operations in one system.

Operate your store data from one control surface.
Keep a single commerce engine as the source of truth.
Expose clean APIs for web and Flutter mobile applications.

Why FrugalDomain Matters

The platform is designed for teams that need fast day-to-day operations from a single admin.

Faster product and inventory operations for daily staff.
Structured sync pipelines with monitoring and retry support.
Reusable API contracts for frontend, mobile, and integrations.
Store-level isolation so each store sees only its own data.

Core Workflows

Catalog Management

Products, variants, collections, tags, vendors, product types.
Warehouse-aware product visibility for channel segmentation.

Inventory & Pricing

Variant-level stock and availability handling.
Bulk and targeted price updates with sync dispatch.

Orders & Checkout

Quote cart totals from backend.
Create draft orders as a checkout pre-step.
Finalize the payment phase by redirecting to the configured checkout URL when enabled.

How To Connect A Store

1. Create and activate the store record in your system.
2. Save the store domain and access token securely.
3. Run initial full sync for products, variants, content, and customers.
4. Enable continuous sync jobs and webhook subscriptions.
5. Verify dashboard sync health before opening access to store staff.

Use one store identity per shop. Never reuse tokens across stores.

Flutter Mobile Integration

Mobile app endpoints are under /mobile and require store context. Always send store_id, and optionally warehouse_name for channel-specific product feeds.

warehouse_name filtering includes exact warehouse items plus global items (null/empty/all).
Use bootstrap endpoint first to preload store branding, featured products, and payment methods.
Use quote endpoint before placing draft orders to show precise totals.

Code

GET /mobile/bootstrap?store_id={uuid}&warehouse_name=BRAND VIP WEB
GET /mobile/products?store_id={uuid}&warehouse_name=BRAND VIP WEB&per_page=20
GET /mobile/collections?store_id={uuid}&warehouse_name=BRAND VIP WEB
GET /mobile/search?store_id={uuid}&warehouse_name=BRAND VIP WEB&q=lip
POST /mobile/checkout/quote
POST /mobile/checkout/place-draft-order

Tools On The Site

Beyond the dashboard, the site ships a set of browser-based tools. They run entirely on the visitor's machine - nothing is uploaded - so they work offline once the page has loaded.

Icon library

324 icons in SVG and PNG, served over the CDN.
Copy a class name, download a single file, or build a collection.
Usable with two lines: link the stylesheet, then use the icon class.

Converters

Images between common raster formats.
Audio and document conversion powered by WebAssembly in the browser.
Files never leave the device, so large inputs are limited only by available memory.

Drawing board and simulator

A vector drawing board with layers, undo and redo.
A touch simulator that records gesture strokes and recognises Arabic characters.

Publishing Applications

Applications can be published alongside the site. Each one gets a gallery card, its own documentation page and an embedded live preview, and is served from its own folder so it keeps its own routing and assets.

1. Add the entry from the dashboard (Apps), choosing the type and the preview mode.
2. Write the documentation sections that appear on the app's page.
3. Build the app with a base path matching its folder, e.g. --base=/apps/my-app/
4. Upload the contents of the build output into apps/<slug>/ on the server.
5. Set the entry to Published, save the catalogue and rebuild the frontend.

Preview modes

Subfolder - served at /apps/<slug>. Upload only, no hosting configuration.
Subdomain - point a subdomain's document root at the app folder and build with base "/".
External - the app is hosted elsewhere and the gallery links out to it.

Routing

The site rewrite excludes /apps/<slug>/... so deep links resolve inside the app.
An app with its own client-side router needs an .htaccess in its folder pointing at its own index.html.

A React or Vue build served from a subfolder must be built with a matching base path. Built with the default base it requests its assets from the site root, every one returns 404, and the preview renders blank.

REST API Guide (Current Public Integration Set)

Use JSON requests and responses. Send Authorization token when route requires protected context. For mobile storefront routes, store_id is required in request.

GET/mobile/bootstrap
Return store profile, featured catalog blocks, and payment method references.
GET/mobile/products
Paginated product listing with optional search and warehouse filter.
GET/mobile/products/{id}
Product details with variants, collections, and tags.
GET/mobile/collections
List collections for current store context.
GET/mobile/collections/{id}
Collection details with collection products.
GET/mobile/pages
Published static pages for the storefront app.
GET/mobile/blogs
Published blogs.
GET/mobile/blogs/{blogId}/articles
Blog articles list for content screens.
GET/mobile/payment-methods
Return enabled local payment toggles and supported method references.
POST/mobile/checkout/quote
Calculate quote totals from variant lines.
POST/mobile/checkout/place-draft-order
Create local draft order as pre-checkout step.

Method	Path	Purpose
GET	/mobile/bootstrap	Return store profile, featured catalog blocks, and payment method references.
GET	/mobile/products	Paginated product listing with optional search and warehouse filter.
GET	/mobile/products/{id}	Product details with variants, collections, and tags.
GET	/mobile/collections	List collections for current store context.
GET	/mobile/collections/{id}	Collection details with collection products.
GET	/mobile/pages	Published static pages for the storefront app.
GET	/mobile/blogs	Published blogs.
GET	/mobile/blogs/{blogId}/articles	Blog articles list for content screens.
GET	/mobile/payment-methods	Return enabled local payment toggles and supported method references.
POST	/mobile/checkout/quote	Calculate quote totals from variant lines.
POST	/mobile/checkout/place-draft-order	Create local draft order as pre-checkout step.

Sample request

{
  "store_id": "your-store-uuid",
  "warehouse_name": "BRAND VIP WEB",
  "lines": [
    { "variant_id": 1201, "quantity": 2 },
    { "variant_id": 1202, "quantity": 1 }
  ]
}

Sample response

{
  "status": "success",
  "data": {
    "totals": {
      "subtotal": 45.0,
      "tax": 0,
      "shipping": 0,
      "discount": 0,
      "grand_total": 45.0
    }
  }
}

Security & Best Practices

Validate store_id and never trust client-side tenant scope.
Use HTTPS only in production and rotate credentials periodically.
Keep access tokens server-side only.
Use idempotency for critical create/update operations.
Log sync failures with correlation identifiers for diagnostics.

Troubleshooting

Products are missing in one mobile channel.

Check warehouse_name sent by the app and verify warehouse_location values in products table.

Quote endpoint returns empty lines.

Ensure variant IDs belong to the same store and match the selected warehouse visibility rules.

Sync counters look stale.

Refresh partner dashboard and verify background queue workers are running.