General

24 API calls in this section.

Verify Mobile Staging Access (Production Only)

Public APIs / General

POST/public/mobile-staging-access/verify

Verifies the global 8–12 digit Operation-app staging PIN. Mobile clients must call this route against the production backend even when their current backend is staging. The public staging switch must be enabled. Raw PINs are redacted from audits. Responses: 200 authorized; 400 malformed PIN; 401 incorrect PIN; 403 disabled; 500 generic failure.

Query parameters

Parameter	Type	Description
language	string	Example: en

Headers

Parameter	Type	Description
Content-Type	string	Example: application/json
X-Ondi-Client	string	Example: eaglepost
X-Ondi-Client-Version	string	Example: 1.0.0

Body parameters

Parameter	Type	Description
passcode	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/public/mobile-staging-access/verify?language=en" \2  --header "Content-Type: application/json" \3  --header "X-Ondi-Client: eaglepost" \4  --header "X-Ondi-Client-Version: 1.0.0" \5  --data-raw '{6  "passcode": "12345678"7}'

Response examples

No saved response example. Use Try it to inspect a staging response.

Get Public System Settings

Public APIs / General

GET/public/system-settings

Retrieves public system settings. When key is provided, returns a single setting by setting_key. Otherwise returns all active public settings, optionally filtered by type.

Public general settings include default_system_language, tenant_available_languages, and default_location. default_location contains numeric latitude and longitude values and reflects the effective tenant override when tenant_id resolves from request context or query. The legacy default_location_cordinates field remains available for backward compatibility.

Frontend integration contract

• Read settings.general.default_location.latitude and settings.general.default_location.longitude for the initial map location.

• GET /public/system-settings?key=default_location returns the same object directly in settings.

Responses

• 200 OK (list)

• 200 OK (single)

• 404 Not Found (when key specified and not found)

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized messages Language code for response localization (Optional, default: en) Language code for localized messages Example: en
keyOptional	string	Optional setting_key to fetch a single public setting setting_key to fetch a specific setting Optional setting_key to fetch a single public setting setting_key to fetch a specific setting
typeOptional	string	Optional setting_type to filter the list (e.g., 'mobile', 'external_links') setting_type to filter the list (e.g., 'mobile', 'external_links', 'general') Optional setting_type to filter the list (e.g., 'mobile', 'external_links') setting_type to filter the list (e.g., 'mobile', 'external_links', 'general')

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/system-settings?language=en&key=&type="

Response examples

200 · Success - All Public Settings200 · Success - Default Location200 · Success - Public Links200 · Success - Single Setting By Key404 · Error - Setting Not Found (by key)500 · Error - Internal Server Error

200OK

Response body

json

1{2  "success": true,3  "message": "system_settings_retrieved_successfully",4  "settings": {5    "general": {6      "default_location": {7        "latitude": 36.20528,8        "longitude": 44.047119      },10      "default_system_language": {11        "default_language": "en"12      },13      "tenant_available_languages": {14        "available_languages": [15          "en",16          "ar",17          "ku",18          "fa"19        ],20        "language_names": {21          "en": "English",22          "ar": "Arabic",23          "ku": "Kurdish",24          "fa": "Farsi"25        }26      }27    }28  }29}

Get Config Versions

Public APIs / General

GET/public/config/versions

Check which cached resources changed before downloading configuration again. Compare each resource’s version number with the version saved by your app, then refetch only resources whose versions changed. The cache_enabled flag reports whether caching is enabled for the resolved scope.

The response separates global, tenant and user version maps. Global-only requests work without authentication; user versions require the matching bearer session. Save the ETag with the maps: a validator matching the server snapshot returns 304 with no body, while 200 returns the current versions.

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Optional tenant UUID. Omit for global versions, or let the bearer session supply its tenant. A conflicting tenant scope returns 403. Optional tenant UUID. Omit for global versions, or let the bearer session supply its tenant. A conflicting tenant scope returns 403. Example: {{tenant_id}}
user_idOptional	string	Optional user UUID. Requires a matching bearer session; the signed-in user is inferred when omitted. A conflicting user scope returns 403. Optional user UUID. Requires a matching bearer session; the signed-in user is inferred when omitted. A conflicting user scope returns 403. Example: {{user_id}}

Headers

Parameter	Type	Description
AuthorizationOptional	string	Bearer session for user-scoped versions. Omit for public global or tenant version maps. Bearer session for user-scoped versions. Omit for public global or tenant version maps. Example: Bearer {{access_token}}
If-None-MatchOptional	string	Previously saved ETag. A matching server validator returns 304. The staging edge currently emits a weak tag that can return 200 when resent unchanged; compare the returned version maps. Responses use Cache-Control: no-store. Previously saved ETag. A matching server validator returns 304. The staging edge currently emits a weak tag that can return 200 when resent unchanged; compare the returned version maps. Responses use Cache-Control: no-store.

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/config/versions?tenant_id=${TENANT_ID}&user_id=${USER_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "If-None-Match: "

Response examples

200 · Success Response304 · Not Modified (ETag Match)400 · Error - Invalid tenant_id

200OK

Response body

json

1{2  "success": true,3  "global": {4    "system.settings": 42,5    "i18n.config": 76  },7  "tenant": {8    "delivery.zones": 11,9    "warehouse.categories": 510  },11  "user": {12    "addresses.list": 313  },14  "server_time": "2026-05-24T10:00:00.000Z"15}

List Storefront Brands

Public APIs / General

GET/public/storefront/{{slug}}/brands

List active brands for a public storefront with pagination and optional search.

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier of the storefront URL-friendly identifier of the storefront

Query parameters

Parameter	Type	Description
pageOptional	string	Page number (optional, default: 1) Page number (optional, default: 1) Example: 1
limitOptional	string	Items per page (optional, default: 20) Items per page (optional, default: 20) Example: 20
searchOptional	string	Search by brand name/description (optional) Search by brand name/description (optional)
languageOptional	string	Language code (optional, default: en) Language code (optional, default: en) Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/brands?page=1&limit=20&search=&language=en"

Response examples

200OK

Response body

json

1{2  "success": true,3  "data": {4    "market": {5      "id": "market-uuid",6      "slug": "my-store-slug",7      "store_name": {8        "en": "My Store"9      },10      "status": "approved"11    },12    "brands": [13      {14        "id": "brand-uuid",15        "name": {16          "en": "Apple",17          "ar": "آبل"18        },19        "slug": "apple",20        "logo_url": "https://example.com/apple.png",21        "is_active": true22      }23    ],24    "pagination": {25      "page": 1,26      "limit": 20,27      "total": 1,28      "totalPages": 129    }30  }31}

Browse Storefront Product Feed

Public APIs / General

GET/public/storefront/{{slug}}/catalog/{{list_type}}

Browse pre-ranked product feeds for a public storefront. Uses SQL procedures for minimal runtime cost and consistent response shape.

Response

• Same shape as catalog browse: { success, data: { market, products, pagination } }

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier of the storefront (e.g., 'my-store-slug') Storefront slug URL-friendly identifier of the storefront (e.g., 'my-store-slug') Storefront slug
list_typeRequired	string	Feed type: trending | new-arrivals | top-selling | recommended One of trending, new-arrivals, top-selling, recommended Feed type: trending | new-arrivals | top-selling | recommended One of trending, new-arrivals, top-selling, recommended Example: trending

Query parameters

Parameter	Type	Description
pageOptional	string	Page number for pagination (Optional, default: 1) Page number (default: 1) Page number for pagination (Optional, default: 1) Page number (default: 1) Example: 1
limitOptional	string	Number of products per page (Optional, default: 12) Items per page (default: 12) Number of products per page (Optional, default: 12) Items per page (default: 12) Example: 12
category_idOptional	string	Filter by category ID (Optional) Filter by category ID (Optional)
window_daysOptional	string	Window in days for ranking (Optional; used by trending/top-selling). Defaults: trending=14, top-selling=90 Ranking window (trending default 14, top-selling default 90) Window in days for ranking (Optional; used by trending/top-selling). Defaults: trending=14, top-selling=90 Ranking window (trending default 14, top-selling default 90)
languageOptional	string	Language code for response localization (Optional, default: en) Localization language code Language code for response localization (Optional, default: en) Localization language code Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/catalog/${LIST_TYPE}?page=1&limit=12&category_id=&window_days=&language=en"

Response examples

200 · Success Response (trending)404 · Error - Store Not Found

200OK

Response body

json

1{2  "success": true,3  "data": {4    "market": {5      "id": "market-uuid",6      "slug": "my-store-slug",7      "store_name": {8        "en": "My Store"9      },10      "status": "approved",11      "banners": []12    },13    "products": [14      {15        "id": "product-uuid",16        "name": {17          "en": "Product Name"18        },19        "description": {20          "en": "Product description"21        },22        "stock_quantity": 10,23        "rating": 4.6,24        "total_reviews": 2325      }26    ],27    "pagination": {28      "page": 1,29      "limit": 12,30      "total": 12,31      "totalPages": 132    }33  }34}

Verify Domain

Public APIs / General

GET/public/verify-domain/:subdomain

Verifies if a domain/subdomain is associated with a tenant in the system.

Path parameters

Parameter	Type	Description
subdomainRequired	string	Subdomain to verify (e.g., 'company' for company.example.com) The subdomain to verify (e.g., 'company' for company.example.com) Subdomain to verify (e.g., 'company' for company.example.com) The subdomain to verify (e.g., 'company' for company.example.com)

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/verify-domain/${SUBDOMAIN}?language=en"

Response examples

200 · Success Response404 · Error - Domain Not Found500 · Error - Internal Server Error

200OK

Response body

json

1{2  "success": true,3  "tenantId": "tenant-uuid",4  "message": "Domain verified successfully"5}

Get System Brand Settings

Public APIs / General

GET/public/system-brand-settings

Retrieves the active system brand settings including brand name, assets, colors, and configurations.

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/system-brand-settings?language=en"

Response examples

200 · Success Response500 · Error Response

200OK

Response body

json

1{2  "success": true,3  "message": "System brand settings retrieved successfully",4  "brandSettings": {5    "brand_name": "System Brand Name",6    "assets": {7      "logo": "https://example.com/logo.png",8      "favicon": "https://example.com/favicon.ico"9    },10    "colors": {11      "primary": "#3f51b5",12      "secondary": "#f50057",13      "accent": "#ff4081"14    },15    "configurations": {16      "theme": "light",17      "defaultLanguage": "en"18    }19  }20}

Get Tenant Brand Settings

Public APIs / General

GET/public/tenants/:tenantId/brand-settings

Retrieves tenant brand settings. Falls back to system defaults if no tenant branding exists. Checks if the tenant exists and is active before returning brand settings.

Path parameters

Parameter	Type	Description
tenantIdRequired	string	ID of the tenant to retrieve brand settings for ID of the tenant to retrieve brand settings for

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/tenants/${TENANTID}/brand-settings?language=en"

Response examples

200 · Success Response - Tenant Brand Settings200 · Success Response - System Default Settings404 · Error - Tenant Not Found404 · Error - Tenant Not Active500 · Error - Internal Server Error

200OK

Response body

json

1{2  "success": true,3  "message": "Tenant brand settings retrieved successfully",4  "brandSettings": {5    "brand_name": "Tenant Brand Name",6    "assets": {7      "logo": "https://example.com/tenant-logo.png",8      "favicon": "https://example.com/tenant-favicon.ico"9    },10    "colors": {11      "primary": "#3f51b5",12      "secondary": "#f50057",13      "accent": "#ff4081"14    },15    "configurations": {16      "theme": "dark",17      "defaultLanguage": "en"18    },19    "metadata": {20      "lastUpdated": "2023-01-01T00:00:00Z"21    }22  }23}

Get Delivery Tracking

Public APIs / General

GET/public/deliveries/:deliveryId/tracking

Public endpoint for real-time delivery tracking. Returns current status, location, and estimated delivery information.

Path parameters

Parameter	Type	Description
deliveryIdRequired	string	UUID of the delivery to track UUID of the delivery to track

Query parameters

Parameter	Type	Description
tracking_tokenOptional	string	Optional security token for accessing protected delivery tracking Security token for accessing protected delivery tracking Optional security token for accessing protected delivery tracking Security token for accessing protected delivery tracking
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/deliveries/${DELIVERYID}/tracking?tracking_token=&language=en"

Response examples

200 · Success Response400 · Error - Missing Delivery ID401 · Error - Invalid Tracking Token404 · Error - Delivery Not Found500 · Error - Internal Server Error200 · Success (200 OK)

200OK

Response body

json

1{2  "success": true,3  "message": "Delivery tracking retrieved successfully",4  "data": {5    "status": "in_transit",6    "currentLocation": {7      "type": "Point",8      "coordinates": [9        -73.935242,10        40.7306111      ]12    },13    "lastLocationAt": "2024-01-01T12:00:00Z",14    "eta": "2024-01-01T15:30:00Z",15    "estimatedTravelTime": 90,16    "estimatedDistanceKm": 25.5,17    "statusTimeline": [18      {19        "status": "picked_up",20        "timestamp": "2024-01-01T12:00:00Z",21        "location": {22          "latitude": 40.73061,23          "longitude": -73.93524224        },25        "notes": "Picked up from warehouse"26      }27    ],28    "type": "Delivery",29    "routePath": {30      "distance": 25.5,31      "duration": 90,32      "polyline": "encoded_polyline_string"33    },34    "destination": {35      "address": "123 Delivery St, New York, NY 10001",36      "latitude": 40.75061,37      "longitude": -73.94524238    }39  }40}

Get Color Palettes

Public APIs / General

GET/public/color-palettes

Retrieves all available color palettes from the system, ordered by creation date (newest first).

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/color-palettes?language=en"

Response examples

200 · Success Response500 · Error Response200 · Success (200 OK)

200OK

Response body

json

1{2  "success": true,3  "message": "Color palettes retrieved successfully",4  "colorPalettes": [5    {6      "id": "uuid-123",7      "created_at": "2024-01-01T00:00:00Z",8      "name": "Default Theme",9      "palette": {10        "primary": {11          "dark": "#007867",12          "main": "#00A76F",13          "light": "#5BE49B",14          "darker": "#004B50",15          "lighter": "#C8FAD6",16          "contrastText": "#FFFFFF"17        },18        "secondary": {19          "dark": "#1939B7",20          "main": "#3366FF",21          "light": "#84A9FF",22          "darker": "#091A7A",23          "lighter": "#D6E4FF",24          "contrastText": "#FFFFFF"25        }26      }27    },28    {29      "id": "uuid-456",30      "created_at": "2024-01-02T00:00:00Z",31      "name": "Ocean Theme",32      "palette": {33        "primary": {34          "dark": "#004080",35          "main": "#0066CC",36          "light": "#4D94FF",37          "darker": "#002654",38          "lighter": "#B3D6FF",39          "contrastText": "#FFFFFF"40        },41        "secondary": {42          "dark": "#2E7A7A",43          "main": "#4DB8B8",44          "light": "#7DD6D6",45          "darker": "#1A4949",46          "lighter": "#C7EEEE",47          "contrastText": "#FFFFFF"48        }49      }50    }51  ]52}

Browse Storefront Products

Public APIs / General

GET/public/storefront/{{slug}}/catalog

Browse products in a public storefront. Returns active products with only primary variants for listing view. Supports recursive category filtering, advanced search, and featured product types.

Featured Types

• most_loved: Products ordered by Most Loved score (wishlist_count × favorite_weight + qualified_review_count × review_weight). Only includes products that have stats calculated.

• Future types: trending, new_arrivals, top_selling (extensible design)

Search Behavior

• When no search is provided: Returns only primary variants

• When search matches product name/description: Returns primary variant only

• When search matches variant name/description: Returns matching variant (may include multiple instances of same product with different variants)

Category Filtering

• When category_id is provided: Returns products from the specified category and all its child categories (recursive)

• Uses database RPC for optimal performance

Example Requests

• Get most loved products: GET /public/storefront/my-store/catalog?featured_type=most_loved

• Get most loved in category: GET /public/storefront/my-store/catalog?featured_type=most_loved&category_id=category-uuid

• Regular browse: GET /public/storefront/my-store/catalog (default ordering)

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier of the storefront (e.g., 'my-store-slug') URL-friendly identifier of the storefront (e.g., 'my-store-slug')

Query parameters

Parameter	Type	Description
pageOptional	string	Page number for pagination (Optional, default: 1) Page number for pagination (default: 1) Page number for pagination (Optional, default: 1) Page number for pagination (default: 1) Example: 1
limitOptional	string	Number of products per page (Optional, default: 12) Products per page (default: 12) Number of products per page (Optional, default: 12) Products per page (default: 12) Example: 12
category_idOptional	string	Filter by category ID and all its child categories (Optional) Filter by category ID and all its child categories recursively Filter by category ID and all its child categories (Optional) Filter by category ID and all its child categories recursively
brand_idOptional	string	Filter by brand ID (Optional) Filter by brand ID (Optional)
searchOptional	string	Search products by name, description, or variant details (Optional) Search products by name, description, or variant details (Optional)
featured_typeOptional	string	Featured product type filter (Optional). Use 'most_loved' to get products ordered by Most Loved score (wishlist + qualified reviews). When not provided, uses default ordering by created_at DESC. Featured product type. Use most_loved to get products ordered by Most Loved score (calculated from wishlist additions and qualified reviews 4-5 stars). When not provided, uses default ordering by created_at DESC. Featured product type filter (Optional). Use 'most_loved' to get products ordered by Most Loved score (wishlist + qualified reviews). When not provided, uses default ordering by created_at DESC. Featured product type. Use most_loved to get products ordered by Most Loved score (calculated from wishlist additions and qualified reviews 4-5 stars). When not provided, uses default ordering by created_at DESC.
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response Language code for response localization (Optional, default: en) Language code for localized response Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/catalog?page=1&limit=12&category_id=&brand_id=&search=&featured_type=&language=en"

Response examples

200 · Success Response404 · Error - Store Not Found200 · Success (200 OK)

200OK

Response body

text

1{2  "success": true,3  "data": {4    "market": {5      "id": "market-uuid",6      "slug": "my-store-slug",7      "store_name": {"en": "My Store"},8      "status": "approved",9      "banners": []10    },11    "products": [12      {13        "id": "product-uuid",14        "name": {"en": "Product Name"},15        "description": {"en": "Product description"},16        "stock_quantity": 10,17        "category": {18          "id": "category-uuid",19          "name": {"en": "Electronics"}20        },21        "variant": {22          "id": "variant-uuid",23          "name": {"en": "Standard Edition"},24          "description": {"en": "Standard variant description"},25          "price": 29.99,26          "sku": "PROD-001",27          "images": ["image1.jpg", "image2.jpg"],28          "stock_quantity": 1029        },30        "rating": 4.6,31        "total_reviews": 2332         }33       }34     ],35     "pagination": {36       "page": 1,37       "limit": 12,38       "total": 50,39       "totalPages": 540     }41   }42 }

Get Storefront Product

Public APIs / General

GET/public/storefront/{{slug}}/products/{{product_id}}

Get detailed information about a specific product including all variants.

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier of the storefront URL-friendly identifier of the storefront
product_idRequired	string	UUID of the product to retrieve UUID of the product to retrieve

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response Language code for response localization (Optional, default: en) Language code for localized response Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/products/${PRODUCT_ID}?language=en"

Response examples

200OK

Response body

json

1{2  "success": true,3  "data": {4    "market": {5      "id": "market-uuid",6      "slug": "my-store-slug",7      "store_name": {8        "en": "My Store"9      }10    },11    "product": {12      "id": "product-uuid",13      "name": {14        "en": "Product Name"15      },16      "description": {17        "en": "Product description"18      },19      "rating": 4.6,20      "total_reviews": 23,21      "variants": [22        {23          "id": "variant-uuid",24          "price": 29.99,25          "stock_quantity": 10,26          "is_primary": true,27          "variant_options": {28            "size": "M",29            "color": "blue"30          }31        }32      ]33    }34  }35}

Get Similar Storefront Products

Public APIs / General

GET/public/storefront/{{slug}}/products/{{product_id}}/similar

Returns random similar products from the same categories as the given product.

• Input: product_id

• Logic: find products sharing at least one category with the reference product, exclude the reference product, only active products with at least one active in-stock variant.

• Output: same product listing shape (one best variant per product).

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier of the storefront (e.g., 'my-store-slug') URL-friendly identifier of the storefront (e.g., 'my-store-slug')
product_idRequired	string	Reference product UUID Reference product UUID

Query parameters

Parameter	Type	Description
limitOptional	string	Number of similar products to return (Optional, default: 10, max: 50) Number of similar products to return (Optional, default: 10, max: 50) Example: 10
languageOptional	string	Language code for response localization (Optional, default: en) Language code for response localization (Optional, default: en) Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/products/${PRODUCT_ID}/similar?limit=10&language=en"

Response examples

200OK

Response body

json

1{2  "success": true,3  "data": {4    "market": {5      "id": "market-uuid",6      "slug": "my-store-slug",7      "store_name": {8        "en": "My Store"9      },10      "status": "approved"11    },12    "products": [13      {14        "id": "product-uuid-2",15        "name": {16          "en": "Similar Product"17        },18        "description": {19          "en": "Similar product description"20        },21        "stock_quantity": 5,22        "variant": {23          "id": "variant-uuid-2",24          "name": {25            "en": "Standard"26          },27          "description": {28            "en": "Variant description"29          },30          "price": 19.99,31          "sku": "PROD-002",32          "images": [33            "image.jpg"34          ],35          "stock_quantity": 536        },37        "rating": 4.2,38        "total_reviews": 1139      }40    ],41    "pagination": {42      "page": 1,43      "limit": 10,44      "total": 1,45      "totalPages": 146    }47  }48}

Get Storefront Categories

Public APIs / General

GET/public/storefront/{{slug}}/categories

Get all categories available in the storefront.

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier of the storefront URL-friendly identifier of the storefront

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response Language code for response localization (Optional, default: en) Language code for localized response Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/categories?language=en"

Response examples

200OK

Response body

json

1{2  "success": true,3  "data": {4    "market": {5      "id": "market-uuid",6      "slug": "my-store-slug",7      "store_name": {8        "en": "My Store"9      }10    },11    "categories": [12      {13        "id": "category-uuid",14        "name": {15          "en": "Electronics"16        },17        "description": {18          "en": "Electronic devices and accessories"19        },20        "parent_id": null,21        "sort_order": 122      }23    ]24  }25}

Get Storefront Information

Public APIs / General

GET/public/storefront/{{slug}}/info

Get basic information about the storefront including branding and theme settings.

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier of the storefront URL-friendly identifier of the storefront

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response Language code for response localization (Optional, default: en) Language code for localized response Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/info?language=en"

Response examples

200 · Success Response200 · Success (200 OK)

200OK

Response body

json

1{2  "success": true,3  "data": {4    "slug": "my-store-slug",5    "is_valid": true,6    "exists": true,7    "market": {8      "id": "market-uuid",9      "slug": "my-store-slug",10      "store_name": {11        "en": "My Store"12      },13      "status": "approved",14      "currency": {15        "currency_code": "IQD",16        "currency_mode": "code",17        "currency_name": "Iraqi Dinar",18        "currency_symbol": "د.ع.‏",19        "system_currency": {20          "currency_code": "USD",21          "currency_mode": "symbol",22          "currency_name": "US Dollar",23          "currency_symbol": "$"24        },25        "exchange_rate_to_system": 226      },27      "logo_url": "https://example.com/logo.png",28      "theme_settings": {29        "primary_color": "#007AFF",30        "secondary_color": "#FFFFFF",31        "accent_color": "#FF9500",32        "theme_style": "modern"33      }34    }35  }36}

Resolve Storefront By Domain

Public APIs / General

GET/public/storefront/resolve-domain

Resolves an active custom domain to the storefront validation payload, including the owning tenant_id, effective tenant currency, explicit default_currency, the effective tenant default_country, and the effective tenant allowed_countries list derived from phone login settings.

Query parameters

Parameter	Type	Description
domain	string	Custom domain to resolve Custom domain to resolve Example: shop.example.com
languageOptional	string	Language code for localized response localization (Optional, default: en) Language code for localized response localization (Optional, default: en) Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/resolve-domain?domain=shop.example.com&language=en"

Response examples

200 · Success Response404 · Error - Store Not Found

200OK

Response body

json

1{2  "success": true,3  "data": {4    "slug": "my-store-slug",5    "is_valid": true,6    "exists": true,7    "market": {8      "id": "market-uuid",9      "tenant_id": "tenant-uuid",10      "slug": "my-store-slug",11      "store_name": {12        "en": "My Store"13      },14      "status": "approved",15      "currency": {16        "currency_code": "IQD",17        "currency_mode": "code",18        "currency_name": "Iraqi Dinar",19        "currency_symbol": "د.ع.‏",20        "system_currency": {21          "currency_code": "USD",22          "currency_mode": "symbol",23          "currency_name": "US Dollar",24          "currency_symbol": "$"25        },26        "exchange_rate_to_system": 227      },28      "default_currency": {29        "currency_code": "IQD",30        "currency_mode": "code",31        "currency_name": "Iraqi Dinar",32        "currency_symbol": "د.ع.‏",33        "system_currency": {34          "currency_code": "USD",35          "currency_mode": "symbol",36          "currency_name": "US Dollar",37          "currency_symbol": "$"38        },39        "exchange_rate_to_system": 240      },41      "default_country": {42        "code": "CA",43        "name": "Canada",44        "dial_code": "+1"45      },46      "allowed_countries": [47        {48          "code": "CA",49          "name": "Canada",50          "dial_code": "+1"51        },52        {53          "code": "IN",54          "name": "India",55          "dial_code": "+91"56        }57      ],58      "logo_url": "https://example.com/logo.png",59      "theme_settings": {60        "primary_color": "#007AFF",61        "secondary_color": "#FFFFFF",62        "accent_color": "#FF9500",63        "theme_style": "modern"64      }65    }66  }67}

Validate Storefront Slug

Public APIs / General

GET/public/storefront/{{slug}}/validate

Validates if a slug exists and points to a published and active storefront. On valid storefronts, the response includes the owning tenant_id, effective tenant currency, explicit default_currency, the effective tenant default_country, and the effective tenant allowed_countries list derived from phone login settings.

**Use Cases:

• Frontend route validation

• Subdomain verification

• URL availability checking

• SEO-friendly URL validation

• Custom domain setup

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier to validate (e.g., 'my-store-slug') URL-friendly identifier to validate (e.g., 'my-store-slug')

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response Language code for response localization (Optional, default: en) Language code for localized response Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/validate?language=en"

Response examples

200 · Success - Valid Slug200 · Success - Invalid Slug200 · Success (200 OK) - Valid Slug

200OK

Response body

json

1{2  "success": true,3  "data": {4    "slug": "my-store-slug",5    "is_valid": true,6    "exists": true,7    "market": {8      "id": "market-uuid",9      "tenant_id": "tenant-uuid",10      "slug": "my-store-slug",11      "store_name": {12        "en": "My Store"13      },14      "status": "approved",15      "currency": {16        "currency_code": "IQD",17        "currency_mode": "code",18        "currency_name": "Iraqi Dinar",19        "currency_symbol": "د.ع.‏",20        "system_currency": {21          "currency_code": "USD",22          "currency_mode": "symbol",23          "currency_name": "US Dollar",24          "currency_symbol": "$"25        },26        "exchange_rate_to_system": 227      },28      "default_currency": {29        "currency_code": "IQD",30        "currency_mode": "code",31        "currency_name": "Iraqi Dinar",32        "currency_symbol": "د.ع.‏",33        "system_currency": {34          "currency_code": "USD",35          "currency_mode": "symbol",36          "currency_name": "US Dollar",37          "currency_symbol": "$"38        },39        "exchange_rate_to_system": 240      },41      "default_country": {42        "code": "CA",43        "name": "Canada",44        "dial_code": "+1"45      },46      "allowed_countries": [47        {48          "code": "CA",49          "name": "Canada",50          "dial_code": "+1"51        },52        {53          "code": "IN",54          "name": "India",55          "dial_code": "+91"56        }57      ]58    }59  }60}

Get Public Advertisements

Public APIs / General

GET/public/storefront/{{slug}}/ads/{{placement}}

Retrieves active advertisements for a specific placement on a public storefront. No authentication required.

• None required - Public endpoint

Response Data

• Only active advertisements within date range

• Sorted by priority (highest first)

• Multi-language content

• Ready for frontend display

Features

• Public access for frontend integration

• Automatic filtering of active/scheduled ads

• Priority-based ordering

• Placement-specific results

• Performance optimized

Use Cases

• Website banner integration

• Mobile app advertisement display

• Category page promotions

• Product page cross-sells

• Checkout upsells

Path parameters

Parameter	Type	Description
slugRequired	string	URL-friendly identifier of the store/market URL-friendly identifier of the store/market
placementRequired	string	Advertisement placement (home, category, product, checkout, global) Advertisement placement (home, category, product, checkout, global)

Query parameters

Parameter	Type	Description
limitOptional	string	Maximum number of advertisements to return (default: 5) Maximum ads to return (default: 5) Maximum number of advertisements to return (default: 5) Maximum ads to return (default: 5) Example: 5

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/${SLUG}/ads/${PLACEMENT}?limit=5"

Response examples

200 · Success - Public Advertisements404 · Error - Store Not Found

200OK

Response body

json

1{2  "success": true,3  "advertisements": [4    {5      "id": "ad-uuid",6      "type": "banner",7      "placement": "home",8      "title": {9        "en": "Special Offer",10        "ar": "عرض خاص",11        "ku": "پێشکەشکراوی تایبەت"12      },13      "content": {14        "en": "Limited time offer - don't miss out!",15        "ar": "عرض لفترة محدودة - لا تفوت الفرصة!",16        "ku": "پێشکەشکراوی کاتی سنووردار - لە دەستت مەدە!"17      },18      "image_url": "https://example.com/special-offer.jpg",19      "link_url": "/special-offers",20      "priority": 10,21      "is_currently_active": true22    }23  ],24  "placement": "home",25  "slug": "my-store-slug",26  "store_name": {27    "en": "My Store",28    "ar": "متجري",29    "ku": "دوکانەکەم"30  }31}

Record Advertisement View

Public APIs / General

POST/public/ads/{{advertisement_id}}/view

Records when an advertisement is viewed by a user. Used for analytics tracking.

• None required - Public endpoint

Features

• Anonymous tracking support

• User session correlation

• Browser fingerprinting

• Geographic tracking via IP

• Graceful error handling

Use Cases

• Impression tracking

• User engagement analysis

• Geographic performance data

• A/B testing metrics

• Campaign reach measurement

Implementation Notes

• Call when advertisement becomes visible

• Handle failures gracefully (don't break user experience)

• Respect privacy regulations

• Consider rate limiting for abuse prevention

Path parameters

Parameter	Type	Description
advertisement_idRequired	string	UUID of the viewed advertisement UUID of the viewed advertisement

Headers

Parameter	Type	Description
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
viewer_info	object	Object containing viewer context Object containing viewer context
viewer_info.user_idOptional	string	Authenticated user ID Authenticated user ID
viewer_info.session_idOptional	string	Session identifier Session identifier
viewer_info.user_agentOptional	string	Browser user agent Browser user agent
viewer_info.ipOptional	string	Client IP address Client IP address

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/public/ads/${ADVERTISEMENT_ID}/view" \2  --header "Content-Type: application/json" \3  --data-raw '{4  "viewer_info": {5    "user_id": "user-uuid",6    "session_id": "session-uuid",7    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",8    "ip": "192.168.1.1"9  }10}'

Response examples

200 · Success - View Recorded200 · Success - Graceful Failure

200OK

Response body

json

1{2  "success": true,3  "message": "View recorded successfully"4}

Record Advertisement Click

Public APIs / General

POST/public/ads/{{advertisement_id}}/click

Records when an advertisement is clicked by a user. Used for conversion tracking and analytics.

• None required - Public endpoint

Features

• Click-through tracking

• User journey correlation

• Conversion attribution

• Geographic click data

• Fraud detection support

Use Cases

• CTR calculation

• Conversion tracking

• User engagement measurement

• Campaign effectiveness

• ROI analysis

• Attribution modeling

Implementation Notes

• Call immediately on advertisement click

• Fire before navigation to target URL

• Handle network failures gracefully

• Consider click fraud prevention

• Respect user privacy settings

Path parameters

Parameter	Type	Description
advertisement_idRequired	string	UUID of the clicked advertisement UUID of the clicked advertisement

Headers

Parameter	Type	Description
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
clicker_info	object	Object containing click context Object containing click context
clicker_info.user_idOptional	string	Authenticated user ID Authenticated user ID
clicker_info.session_idOptional	string	Session identifier Session identifier
clicker_info.user_agentOptional	string	Browser user agent Browser user agent
clicker_info.ipOptional	string	Client IP address Client IP address

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/public/ads/${ADVERTISEMENT_ID}/click" \2  --header "Content-Type: application/json" \3  --data-raw '{4  "clicker_info": {5    "user_id": "user-uuid",6    "session_id": "session-uuid",7    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",8    "ip": "192.168.1.1"9  }10}'

Response examples

200 · Success - Click Recorded200 · Success - Graceful Failure

200OK

Response body

json

1{2  "success": true,3  "message": "Click recorded successfully"4}

List Storefront Markets (with primary variant)

Public APIs / General

GET/public/storefront/markets

Returns a paginated list of published markets, each with at most one primary active variant. Useful for discovery/listing pages.

Response

• markets: Array of markets, each with country { code, name, dial_code } and optional primary_variant

• pagination: page, limit, total, totalPages

Query parameters

Parameter	Type	Description
pageOptional	string	Page number (default: 1) Page number (default 1) Page number (default: 1) Page number (default 1) Example: 1
limitOptional	string	Items per page (default: 10) Page size (default 10) Items per page (default: 10) Page size (default 10) Example: 10
searchOptional	string	Search by store name or slug (optional) Filter by store name or slug Search by store name or slug (optional) Filter by store name or slug
languageOptional	string	Localization language (optional, default: en) Localization language code Localization language (optional, default: en) Localization language code Example: en
countryOptional	string	Optional. ISO 3166-1 alpha-2/alpha-3. Filters by tenant domestic country (tenant_settings override, else system_settings default). ISO country code; filters by tenant domestic country (system_settings / tenant_settings domestic_country) Optional. ISO 3166-1 alpha-2/alpha-3. Filters by tenant domestic country (tenant_settings override, else system_settings default). ISO country code; filters by tenant domestic country (system_settings / tenant_settings domestic_country)

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/storefront/markets?page=1&limit=10&search=&language=en&country="

Response examples

200OK

Response body

json

1{2  "success": true,3  "data": {4    "markets": [5      {6        "id": "market-uuid-1",7        "code": 1000,8        "slug": "store-one",9        "store_name": {10          "en": "Store One"11        },12        "status": "approved",13        "publish_status": "published",14        "logo_url": "https://example.com/logo.png",15        "theme_settings": {16          "primary_color": "#007AFF"17        },18        "banners": [],19        "country": {20          "code": "CA",21          "name": "Canada",22          "dial_code": "+1"23        },24        "primary_variant": {25          "id": "variant-uuid-1",26          "name": {27            "en": "Default Variant"28          },29          "description": null,30          "price": 29.99,31          "images": [],32          "product_id": "product-uuid-1"33        }34      },35      {36        "id": "market-uuid-2",37        "code": 1001,38        "slug": "store-two",39        "store_name": {40          "en": "Store Two"41        },42        "status": "approved",43        "publish_status": "published",44        "logo_url": null,45        "theme_settings": {},46        "banners": [],47        "country": null,48        "primary_variant": null49      }50    ],51    "pagination": {52      "page": 1,53      "limit": 10,54      "total": 2,55      "totalPages": 156    }57  }58}

Get OneSignal Public Config

Public APIs / General

GET/public/push/onesignal

Returns the public OneSignal App ID for frontend use.

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/push/onesignal"

Response examples

200OK

Response body

json

1{2  "success": true,3  "appId": "05a0dd64-de54-4a08-a65e-dd8f2b52b686"4}

Create Demo Request

Public APIs / General

POST/public/demo-request

Submits a new demo request from a prospective tenant.

Headers

Parameter	Type	Description
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
nameRequired	string	Contact person's name (2-100 chars) Contact person's name (2-100 chars)
emailRequired	string	Valid email address Valid email address
phone_numberRequired	string	Contact number (6-20 chars) Contact number (6-20 chars)
notesOptional	string	Additional details or requirements (max 2000 chars) Additional details or requirements (max 2000 chars)
interested_modulesOptional	array<string>	Array of modules interested in (e.g., 'delivery', 'storefront', 'restaurant') Array of modules interested in (e.g., 'delivery', 'storefront', 'restaurant')

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/public/demo-request" \2  --header "Content-Type: application/json" \3  --data-raw '{4  "name": "John Doe",5  "email": "john.doe@company.com",6  "phone_number": "+15551234567",7  "notes": "We are a logistics company looking to modernize our fleet management.",8  "interested_modules": [9    "delivery",10    "storefront"11  ]12}'

Response examples

201 · Success Response400 · Error - Validation Failed201 · Success (201 Created)400 · Error (400 Bad Request) - Validation Failed

201Created

Response body

json

1{2  "success": true,3  "message": "demo_request_submitted_successfully",4  "data": {5    "id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",6    "status": "Requested"7  }8}

List Public System Modules

Public APIs / General

GET/public/system-modules

Retrieves a list of active public system modules. Useful for populating dropdowns in forms like 'Request Demo'.

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Example: en

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/public/system-modules?language=en"

Response examples

200OK

Response body

json

1{2  "success": true,3  "message": "modules_retrieved_successfully",4  "modules": [5    {6      "code": "delivery",7      "name": "Delivery Management",8      "description": "Comprehensive delivery tracking and fleet management"9    },10    {11      "code": "storefront",12      "name": "E-commerce Storefront",13      "description": "Online store builder and management"14    }15  ]16}