FAQs

Q1. What is Foundation Service and why do I need it?

It is the configuration backbone of the Equinox platform. Before any other service can create data — products, orders, users, inventory — it needs to know which business and store to scope that data to. Foundation is where those businesses and stores are defined. Every other service is downstream of Foundation and cannot function without it.

Q2. Why is Foundation the first service to configure for a new tenant?

Every other service scopes its data by businessId and storeId. If the business and store records don’t exist here, other services will reject requests because they cannot resolve the tenant context. You must set up Foundation before PIM products, OMS orders, or user accounts can be created.

Q3. What happens if I skip Foundation setup and go directly to PIM or OMS?

PIM and OMS will reject all create requests with a not-found error because the storeId in the request body does not exist in Foundation’s stores collection. The platform enforces that the store must exist before any service-specific data can be created for it.

Q4. How does store property inheritance work?

When a child store is created with a parentStoreId, the service records the full hierarchyPath array (e.g. [1000, 1100, 1150]). When GET /v1/stores/:storeId/effective-config is called, the service fetches all ancestors in one MongoDB query and merges their properties objects from root to leaf — the leaf (deepest child) always wins. For example if the root store sets theme: "dark" and the leaf store sets theme: "light", the effective config returns theme: "light". The result is Redis-cached, so subsequent calls return the cached value instantly.

Q5. What happens if I try to delete a store that has children?

The delete will fail with EQ-FND-4090995 CANNOT_DELETE_STORE_WITH_CHILDREN. You must first delete or re-parent all child stores. Call GET /v1/stores/:storeId/descendants to find all descendants, then delete them from the deepest level (level 3) upward.

Q6. What is the difference between stores.properties and stores.serviceProperties?

properties is a free-form key-value map owned by the store (e.g. branding config, feature toggles). It participates in hierarchy inheritance — child stores inherit parent property keys and can override individual values. serviceProperties is a structured array of { serviceName, propertyName, value } entries — consumed by other Equinox services (PIM, OMS, etc.) to look up service-specific config. serviceProperties do not participate in hierarchy inheritance.

Q7. What is the difference between a Site and a Store?

A Store is the internal configuration unit — it holds properties, a hierarchy, a currency, and a locale. It is the scope for products, inventory, and orders. A Site is the customer-facing access point — it represents the web domain (shop.acme.com) where customers browse. A Site is linked to a Store. In a simple setup there is one store and one site. In a marketplace, multiple Sellers operate on the same Site but each fulfils from their own Store.

Q8. How does the Batch Framework trigger a Lambda?

1. Admin creates a Batch → creates a Job → creates a Schedule with a cron expression and type SCHEDULED.
2. Foundation calls AWS EventBridge PutRule to create a cron rule pointing to the Lambda ARN.
3. When the cron fires, EventBridge publishes batch.job.initiated to the configured event bus.
4. The target Lambda (PIM import Lambda, OMS export Lambda, etc.) receives the event and starts processing.
5. The Lambda calls POST /history/:runRequestId/progress periodically to report progress.
6. When done, the Lambda calls POST /history/:runRequestId/status with COMPLETED or FAILED.
7. Foundation updates the execution record and publishes batch.execution.completed.

Q9. How do I run the service without AWS credentials locally?

The simplest fully-offline setup is in-memory mode, which stubs out MongoDB, Redis, and the event publisher:

FOUNDATION_USE_INMEMORY=true
STAGE=test           # keeps the live EventBridge plugin from publishing (it is gated by STAGE !== 'test')

With FOUNDATION_USE_INMEMORY=true the service needs no external infrastructure (data is lost on restart).

Note: there is no ENABLE_EVENT_BRIDGE, SKIP_LAMBDA_INVOCATION, or ENABLE_JWT_AUTH variable read in this service’s source (older docs listed these). Event publishing is gated by STAGE; JWT validation is handled by the shared auth plugin.

Q10. What is master data and who manages it?

Master data (currencies, locales, timezones, countries, store types) is seeded into MongoDB once during initial platform setup and treated as read-only through the API — no POST, PATCH, or DELETE routes exist for these collections. To add a new currency or locale, a database migration script must be run directly against MongoDB. All other services validate their inputs against these collections (e.g. PIM validates defaultLocale against the locales collection before saving a product).

Q11. How does ship-from-store (SFS) work?

Locations have a shipFromStore boolean flag. When the inventory service needs to route a stock reservation for an online order, it calls GET /v1/locations/proximity with the customer’s lat/lng and a radius to find the nearest ACTIVE SFS-enabled locations. It then picks the closest eligible one for fulfilment. Use PUT /v1/locations/sfs/bulk to toggle SFS on or off across many locations in a single API call.

Q12. Why does the Redis cache sometimes serve stale data?

The effective-config cache is invalidated on every mutation to a store or its ancestors. If you see stale data, check that CACHE_ENABLED=true and that the Redis connection is healthy. During a Redis outage, the service falls back to reading directly from MongoDB — data is never wrong, just slower. If you need to force-invalidate for a specific store, do a no-op PATCH (send the same value for any property) on that store to trigger cache invalidation for it and all its descendants.

Q13. How do I test my changes to store properties without affecting production data?

Use GET /v1/stores/:storeId/effective-config to preview the resolved config after any property change. If you need to test the hierarchy, set up a separate branch in a staging environment and call the /ancestors, /descendants, and /effective-config endpoints to inspect the merge result before promoting to production. You can also run the service in FOUNDATION_USE_INMEMORY=true mode for completely isolated testing without any persistent state.

Q14. Can I have a store without a business?

No. Every store must belong to an existing business — businessId is required on POST /v1/stores. Attempting to create a store with a businessId that does not exist returns EQ-FND-4040109 STORE_BUSINESS_NOT_FOUND. Create the business first.

Q15. What does “soft-delete” mean? Is the data really gone?

No — soft-delete sets the record’s status to inactive (or adds a deletedAt timestamp) but does not remove the document from MongoDB. The record is excluded from normal list queries but can still be found by admins querying for inactive records. To permanently remove data (e.g. for GDPR compliance), use the GDPR data deletion workflow.

Q16. What is the “extension framework” and why would I use it?

Foundation lets a tenant plug in custom validators (for stores, sites, locations, sellers) and lifecycle pre/post handlers without changing Foundation’s code. For example, one instance might require store names to match a corporate pattern, or need to enrich a create request before it is saved. These extensions are configured per instance and loaded at runtime from an approved npm package, EFS file, or S3 object. See Extension & Lifecycle Framework – Foundation – Infosys Equinox Developer Portal.

Q17. A create request behaved differently than the API doc says — could an extension be involved?

Yes. If the instance has a lifecycle pre-handler, it can abort or modify a request before it reaches the core logic; a post-handler can rewrite the response body. And a custom validator can reject a payload the built-in rules would accept (returning STORE_VALIDATION_FAILED with extension-specific error details). Check the instance’s pluginConfig to see which extensions are active. See Extension & Lifecycle Framework – Foundation – Infosys Equinox Developer Portal.

Q18. What exactly does the GDPR feature do?

Two AWS Step Functions pipelines. Export collects a subject’s data across services and produces a downloadable file (Foundation runs the initialize/finalize/failure steps and generates a pre-signed S3 URL that expires per GDPR_EXPORT_PRESIGNED_URL_EXPIRY). Delete resolves the affected collections (with a retentionDays fast-fail guard), fans out deletion to user/cart/oms/subscription services, and anonymises audit fields (createdBy/updatedBy) on Foundation’s locations, location events, and batch history. See GDPR – Foundation – Infosys Equinox Developer Portal.

Q19. Does the /health endpoint actually check the database?

Yes. GET /health actively pings MongoDB (db.admin().ping()) and round-trips Redis (set/get/delete), then reports each dependency as connected, in-memory, not_configured, or disconnected, along with uptime and environment. It is not a static 200. There is a separate /metrics endpoint; there is no separate readiness/liveness split.

Revision History
2026-08-04 | AN – Created the page and added the content.