FAQs

Q1. What framework and datastore does the Marketplace Service use?

Fastify v5 (TypeScript) running as an AWS Lambda or a standalone server, backed by MongoDB (marketplacedb_${STAGE}) with optional Redis caching.

Q2. What is the difference between an “app” and a “connector”?

They’re the same registry entity. “Connector” emphasises the deployment/invocation aspect — how the platform loads the code (bundled npm/Maven artifact, Lambda, or external HTTP) and how it reaches a downstream target system (invocationTarget).

Q3. Which capabilities are actually enforced?

Only PAYMENT has first‑class handling (a registered payment-v1 contract, dedicated payment/provider endpoints, and enable‑time gating). Other capability strings are stored as metadata; notification behaviour keys off an app’s notification category, not a capability flag. IAM/ADDRESS_VALIDATION are not special‑cased.

Q4. How does an app get from creation to being usable in a store?

Register (draft) → submit (pending) → approve (approved) → enable at business level → (for PAYMENT, configure payment first) → enable at store level (first app for an interface becomes default). Each step is validated and audited.

Q5. What events does the service emit and who consumes them?

It publishes app.* and business.app.* events on EventBridge (source: marketplace-service). Rule eq-9-marketplace-event-rule fans everything with detail-type prefix app. out to the User, PIM, Subscription, OMS and Cart service Lambdas. Publishing is disabled when STAGE=test.

Q6. How do apps register themselves automatically?

Via POST /v1/apps/self-register using an X-App-Api-Key, or via an app.deployed EventBridge event from the CI/CD pipeline (source: custom.pipeline) — both trigger the same idempotent self‑registration. Auto‑approve is on unless MARKETPLACE_APP_AUTO_APPROVE=false.

Q7. What error format should clients expect?

{ errorCode, errorMessage, validations?, details? } with the HTTP status derived from the code (the digits after EQ-MKT-) and an Error-Code response header. Marketplace codes use the EQ-MKT- prefix; some instance errors reuse EQ-INS-.

Q8. How is per‑tenant configuration handled?

Through layered config overrides (business → store → service) merged into an effective config, including a serviceInstanceMap. There is no separate live per‑instance CRUD API — the instance routes exist in code but are not wired.

Q9. What happens when I disable or drain a payment app?

Drain sets the enablement to DRAINING (rejects new transactions, lets in‑flight captures/refunds finish) and emits app.draining; new work then returns APP_DRAINING (422). Disable removes the enablement and, if it was the default, promotes another enabled app; it emits app.disabled.

Q10. Is authentication ever skipped?

Only when AUTH_ENABLED=false (local development), which bypasses both JWT and API‑key authentication. In deployed stages, JWT (or API key for self‑register) is always enforced.

Revision History
2026-08-05 | JP – Created the page and added the content.