Storefront Extensions

Storefront extensions let apps inject UI directly into the customer-facing store — product pages, checkout, homepage, cart, header, and footer. Unlike dashboard extensions which only merchants see, storefront extensions are visible to shoppers.

There are two rendering modes (same as dashboard extensions):

• JSON mode — Declarative UI tree rendered natively by the storefront. No iframe, no hosting. 35+ components including storefront-specific widgets like ratings, countdown timers, trust badges, and product cards.
• Sandbox mode — Your JavaScript runs inside an isolated <iframe sandbox="allow-scripts">. You control rendering, communicate via postMessage.

Storefront Targets

Every storefront extension declares a target starting with storefront. — this determines where it renders on the store.

How It Works

1. App registers extension with a storefront.* target
2. App is installed by a store
3. Storefront fetches extensions via GET /api/apps/extensions/storefront
4. StorefrontSlot renders each extension with the StorefrontRenderer
5. Extensions receive page context (product_id, store_id, cart data, etc.)
6. Actions (button clicks) are proxied to your backend via POST /api/apps/extensions/storefront/action

Key Differences from Dashboard Extensions

Public API Endpoints

Fetch Storefront Extensions

GET /api/apps/extensions/storefront?store_id={id}&targets={target1},{target2}

No authentication required. Only accepts storefront.* targets — admin targets are rejected with 400.

Response:

{
  "status": 200,
  "data": {
    "storefront.product.block": [
      {
        "extension_id": "my-reviews",
        "app_id": 42,
        "target": "storefront.product.block",
        "title": "Customer Reviews",
        "mode": "json",
        "ui": { "type": "Card", "children": [...] },
        "initial_state": {},
        "installation_id": 99,
        "app_name": "ReviewApp",
        "app_slug": "review-app"
      }
    ]
  }
}

Storefront Action Proxy

POST /api/apps/extensions/storefront/action

No authentication required. Validates installation_id + store_id against the database. Only works for apps with active storefront.* extensions.

Request body:

{
  "installation_id": 99,
  "store_id": 3,
  "action_url": "https://myapp.com/api/reviews/submit",
  "method": "POST",
  "body": { "product_id": 42, "rating": 5, "comment": "Great!" }
}

The backend generates a session token and forwards the request to your app with:

• Authorization: Bearer <session_token> header
• X-SeloraX-Store-Id header
• X-SeloraX-Installation-Id header
• X-SeloraX-Source: storefront header (so you can distinguish storefront vs admin requests)

Rate limited: 60 requests per minute per installation.

SSRF protection: action_url hostname must match your app's registered app_url.

Response Directives

Your app backend can return directives that the storefront automatically processes:

{
  "show_toast": { "message": "Review submitted!", "type": "success" },
  "update_state": { "submitted": true, "review_count": 43 },
  "update_ui": { "type": "Card", "children": [...] },
  "navigate": { "url": "/products/other-product" },
  "open_link": { "url": "https://example.com" },
  "refresh_extensions": true
}