fynd-extension

Original：🇺🇸 English

Translated

Guides development and debugging of Fynd extensions using the FDK (Fynd Development Kit). Covers backend layout (Express, platform/partner/basic routes), webhooks, company-scoped config, and common patterns for catalog, custom, and platform-scoped extensions. Use when working on any Fynd extension, FDK, Fynd Platform APIs, partner panel, or extension webhooks.

1installs

Sourcemridul-devx/fynd-extension-best-practices

Added on2026-02-13

NPX Install

npx skill4agent add mridul-devx/fynd-extension-best-practices fynd-extension

SKILL.md Content

View Translation Comparison →

Fynd Extension (FDK) — Rules and context for the AI

When working on a Fynd extension codebase, follow these rules and use this context so your suggestions stay correct and consistent with FDK.

Rules (always apply)

Company context: Every Fynd Platform API call must be scoped to a company. Always obtain
```
companyId
```
from the request (
```
x-company-id
```
header,
```
company_id
```
in query/body, or your DB) and use
```
getPlatformClient(companyId)
```
— never call platform APIs without a company-scoped client.
Route mount order: Custom webhooks and extension API routes must be mounted before
```
fdkExtension.fdkHandler
```
. If you add a new route, place it before the FDK handler in the server file so it is not swallowed by the catch-all.
Fynd API access: Use only
```
fdkExtension.getPlatformClient(companyId)
```
to get a client for Fynd Platform APIs (catalog, order, application, etc.). Do not construct API clients manually.
Webhook handlers (Fynd → extension): Handlers registered in
```
webhook_config.event_map
```
must have the signature
```
(event_name, request_body, company_id, application_id)
```
. Always use
```
company_id
```
and
```
application_id
```
to scope any DB writes or API calls inside the handler.
Inbound webhooks (external → extension): Any POST route that receives callbacks from an external system must be mounted before the FDK handler. Resolve
```
companyId
```
from the payload or your DB before calling
```
getPlatformClient(companyId)
```
; if you cannot resolve it, return 4xx and do not call Fynd APIs.
Extension-owned entities: When listing or returning platform entities that belong to an extension (e.g. schemes, accounts), always filter by
```
extension_id === process.env.EXTENSION_API_KEY
```
so only this extension’s resources are shown.
Backend entrypoint: FDK is configured in a single backend module (e.g.
```
backend/fdk.js
```
) via
```
setupFdk()
```
. The server mounts
```
fdkHandler
```
,
```
platformApiRoutes
```
,
```
partnerApiRoutes
```
, and the webhook route; do not duplicate FDK setup or mount the same paths twice.

Quick context

FDK module: Exports

fdkHandler

,

getPlatformClient(companyId)

,

platformApiRoutes

,

partnerApiRoutes

,

webhookRegistry

. Use the same instance everywhere.

Routers: Platform routes (e.g. catalog) under
```
/api
```
; partner routes under
```
/apipartner
```
; extension-specific routes under
```
/apibasic
```
or your own prefix. All need
```
companyId
```
and
```
getPlatformClient(companyId)
```
when calling Fynd.
Event names and payloads: Depend on extension type. Refer to Fynd Partner docs when adding or debugging webhooks.

When adding or changing behavior

New API route: Add a router in the backend, mount it in the server before the FDK handler; in the route, read
```
companyId
```
(e.g. from
```
x-company-id
```
), call
```
getPlatformClient(companyId)
```
, then call Fynd APIs.

New Fynd webhook: Add the event to

webhook_config.event_map

in the FDK module with

{ handler, version }

; implement the handler with signature

(event_name, request_body, company_id, application_id)

.

New inbound webhook: Add a POST route and mount it before
```
fdkHandler
```
; in the handler, resolve
```
companyId
```
, then
```
getPlatformClient(companyId)
```
and Fynd APIs as needed.
Extension-specific logic: Attach to the appropriate router (platform/partner/basic); when returning lists from the platform that are extension-scoped, filter by
```
extension_id === process.env.EXTENSION_API_KEY
```
.

References (load when needed)

references/fdk-setup.md — FDK setup rules, env vars, route order.
references/webhooks.md — Webhook registration and inbound webhook rules.
references/extension-patterns.md — Rules by extension type (catalog, platform-scoped, custom).