# Shopgate Documentation

> Shopgate provides two products. **Shopping Apps** are native iOS/Android shopping apps for merchants, built on the Shopgate CONNECT platform: a React/Redux frontend ("Engage") that is customized through themes and extensions, and a Node.js backend that runs "pipelines" made of "steps". The **Omnichannel Suite** is a set of REST services (catalog, customer, order, import, webhook) for inventory, order routing, ship-from-store, click & collect and related use cases.

Key facts for code generation:

- Shopping App extensions are Node.js + React packages installed into a local workspace and managed with the `sgconnect` CLI from `@shopgate/platform-sdk`.
- Extension IDs follow `@<organization>/<name>`. A pipeline id starts with the organization id and the file name must match the id (`<pipelineId>.json`); Shopgate's own pipelines use the longer `<organization>.<collection>.<action>.<version>` form.
- Backend logic is written as *steps* (plain async JS functions) that are wired into *pipelines* (JSON) or injected into existing pipelines via *hooks*.
- Frontend customization happens through *portals* (named extension points in the theme), Redux *streams*, *actions*, *selectors* and *hooks* — not by forking the theme.
- Omnichannel REST services live at `https://<serviceName>.shopgate.io/v<version>/merchants/{merchantCode}/<entity>` and require an OAuth2 bearer token from `https://auth.shopgate.io/oauth/token`.
- Every Omnichannel request needs an `Authorization: Bearer <accessToken>` header. Access tokens expire after 1 hour; refresh tokens are valid for 3 months.
- Pipeline requests time out after 20 seconds and fail with `ETIMEOUT`.

## Start here

- [Primer for AI Agents](https://docs.shopgate.com/agents/): The whole mental model on one page — local setup, extension anatomy, steps and pipelines, portals, and the authenticated Omnichannel REST calls. Read this before generating any Shopgate code.

## Getting started (Shopping Apps)

- [Set Up Your Developer Environment](https://docs.shopgate.com/shopping-apps/introduction/getting-started/set-up-environment/): Prerequisites (Node.js 18+, Git), installing `@shopgate/platform-sdk` globally, `sgconnect login`, starting a project.
- [Set Up Local Frontend](https://docs.shopgate.com/shopping-apps/introduction/getting-started/set-up-local-frontend/): Running the theme locally against a sandbox app.
- [Test With Cloud Flight](https://docs.shopgate.com/shopping-apps/introduction/getting-started/test-with-cloud-flight/): Testing changes on real devices.
- [Development Process](https://docs.shopgate.com/shopping-apps/introduction/shopgate-connect/development-process/): The end-to-end flow from local development to a released extension.
- [Platform SDK](https://docs.shopgate.com/shopping-apps/guides/tools/platform-sdk/): The `sgconnect` CLI — attaching extensions, starting backend and frontend, uploading.

## Architecture (Shopping Apps)

- [App Architecture](https://docs.shopgate.com/shopping-apps/introduction/connect-architecture/app-architecture/): How the native shell, the web frontend and the CONNECT backend fit together.
- [Infrastructure Overview](https://docs.shopgate.com/shopping-apps/introduction/connect-architecture/infrastructure-overview/): Hosting and runtime model.
- [Backend Communication](https://docs.shopgate.com/shopping-apps/introduction/connect-architecture/backend-communication/): How the app talks to the backend via pipeline requests.
- [Extending Your App](https://docs.shopgate.com/shopping-apps/introduction/connect-architecture/extending-your-app/): The extension model.
- [Commerce Integration](https://docs.shopgate.com/shopping-apps/introduction/shopgate-connect/commerce-integration/): How a shop system is connected.

## Tutorials (start here for a first extension)

- [Hello World: Overview](https://docs.shopgate.com/shopping-apps/tutorials/starter/hello-world/overview/): Goal and structure of the starter tutorial.
- [Hello World 1: Create first extension](https://docs.shopgate.com/shopping-apps/tutorials/starter/hello-world/part-1/): `sgconnect extension create`, resulting folder structure (`/extension`, `/pipelines`, `/frontend`, `extension-config.json`).
- [Hello World 2: Build first pipeline](https://docs.shopgate.com/shopping-apps/tutorials/starter/hello-world/part-2/): Writing a step file, wiring it into a pipeline JSON, testing via `sgconnect backend start` and `POST http://localhost:8090/pipelines/<pipelineId>`.
- [Hello World 3: Modify existing pipelines](https://docs.shopgate.com/shopping-apps/tutorials/starter/hello-world/part-3/): Extending Shopgate's own pipelines through hooks.
- [Hello World 4: Interact with storage](https://docs.shopgate.com/shopping-apps/tutorials/starter/hello-world/part-4/): Using the storage step context.
- [Loyalty Points: Backend](https://docs.shopgate.com/shopping-apps/tutorials/starter/loyalty-points/backend/): A realistic backend extension.
- [Loyalty Points: Frontend](https://docs.shopgate.com/shopping-apps/tutorials/starter/loyalty-points/frontend/): The matching frontend extension.
- [Integrate a Search Provider](https://docs.shopgate.com/shopping-apps/tutorials/advanced/search-provider/): Replacing search with a third-party provider.
- [Integrate a Tracking Provider](https://docs.shopgate.com/shopping-apps/tutorials/advanced/tracking-provider/): Building a tracking extension that registers for app events.
- [E-Commerce Platform Integration](https://docs.shopgate.com/shopping-apps/tutorials/advanced/ecp-integration/): Connecting a shop system end to end.

## Backend guides (extensions, pipelines, steps)

- [Extension Configuration](https://docs.shopgate.com/shopping-apps/guides/technical/connect/extension-configuration/): How `extension-config.json` is structured and resolved.
- [Pipelines](https://docs.shopgate.com/shopping-apps/guides/technical/connect/pipelines/): What a pipeline is, trusted vs. regular environments, naming conventions, the 20s timeout.
- [Steps](https://docs.shopgate.com/shopping-apps/guides/technical/connect/steps/): Writing step functions and their `(context, input)` signature.
- [Step Insertion](https://docs.shopgate.com/shopping-apps/guides/technical/connect/step-insertion/): Injecting steps into existing pipelines via hooks.
- [Product Extensibility](https://docs.shopgate.com/shopping-apps/guides/technical/connect/product-extensibility/): Adding custom data to products.

## Frontend guides (Engage / theme)

- [Portals](https://docs.shopgate.com/shopping-apps/guides/technical/engage/portals/): The primary extension mechanism for the UI.
- [Create Custom Routes](https://docs.shopgate.com/shopping-apps/guides/technical/engage/creating-custom-routes/): Adding own pages to the app.
- [Custom Widgets](https://docs.shopgate.com/shopping-apps/custom-widgets/): Widgets configurable by merchants in the CMS.
- [Streams](https://docs.shopgate.com/shopping-apps/guides/technical/engage/streams/): Reacting to app events with RxJS streams.
- [Data Fetching and Processing](https://docs.shopgate.com/shopping-apps/guides/technical/engage/data-fetching-and-processing/): Calling pipelines from the frontend.
- [Retrieving Data from the Store](https://docs.shopgate.com/shopping-apps/guides/technical/engage/retrieving-data/): Selectors and state access.
- [Styling Components](https://docs.shopgate.com/shopping-apps/guides/technical/engage/styling-components/): The styling approach used by the themes.
- [Using the Translation System](https://docs.shopgate.com/shopping-apps/guides/technical/engage/using-the-translation-system/): i18n in extensions.
- [Mutable Actions](https://docs.shopgate.com/shopping-apps/guides/technical/engage/mutable-actions/): Intercepting and changing actions.
- [Form Builder](https://docs.shopgate.com/shopping-apps/guides/technical/engage/form-builder/): Building configurable forms.
- [Extending the Built-in Scanner](https://docs.shopgate.com/shopping-apps/guides/technical/engage/extending-the-built-in-scanner/): Barcode/QR scanner customization.
- [Consent Manager](https://docs.shopgate.com/shopping-apps/consent-manager/): Handling tracking consent.
- [Requesting App Permissions](https://docs.shopgate.com/shopping-apps/requesting-app-permissions/): Asking for native permissions.
- [Accessibility](https://docs.shopgate.com/shopping-apps/accessibility/): Accessibility requirements and helpers.

## Commerce integration (Shopping Apps)

- [E-Commerce Integration Checklist](https://docs.shopgate.com/shopping-apps/guides/commerce/existing-interfaces/): What a shop system must provide.
- [Web Checkout Overview](https://docs.shopgate.com/shopping-apps/guides/commerce/webcheckout/overview/): Using the shop's own web checkout inside the app.
- [Web Checkout: Steps to Integrate](https://docs.shopgate.com/shopping-apps/guides/commerce/webcheckout/steps-to-integrate/): Basic and advanced integration.
- [Web Checkout: Shop System Integration](https://docs.shopgate.com/shopping-apps/guides/commerce/webcheckout/integration-shop-system-shopgate-app/): The handover between app and shop.
- [Cart Integration SDK](https://docs.shopgate.com/shopping-apps/guides/commerce/cart-integration/cart-integration-sdk/): The legacy cart integration route.
- [Cart Integration Plugin API](https://docs.shopgate.com/shopping-apps/guides/commerce/cart-integration/plugin-api/): Plugin API reference.
- [Connect Your Shop](https://docs.shopgate.com/shopping-apps/guides/commerce/cart-integration/connect-your-shop/ecommerce-integration/): Connecting an existing shop.

## Backend reference (Shopping Apps)

- [Extension Config Reference](https://docs.shopgate.com/shopping-apps/references/connect/extensions/configuration/): Full `extension-config.json` schema — `id`, `version`, `trusted`, `configuration`, `components`, `steps`.
- [Pipeline Reference: Overview](https://docs.shopgate.com/shopping-apps/references/connect/extensions/pipeline/overview/): Pipeline file format.
- [Common Step Structure](https://docs.shopgate.com/shopping-apps/references/connect/extensions/pipeline/common-step-structure/): Fields shared by all step types.
- [Extension Step](https://docs.shopgate.com/shopping-apps/references/connect/extensions/pipeline/extension-step/): Calling own step files.
- [Hook Step](https://docs.shopgate.com/shopping-apps/references/connect/extensions/pipeline/hook-step/): Extension points inside pipelines.
- [Pipeline Step](https://docs.shopgate.com/shopping-apps/references/connect/extensions/pipeline/pipeline-step/): Calling another pipeline.
- [Conditional Step](https://docs.shopgate.com/shopping-apps/references/connect/extensions/pipeline/conditional-step/): Branching.
- [Auth Step](https://docs.shopgate.com/shopping-apps/references/connect/extensions/pipeline/auth-step/): Authentication in pipelines.
- [Error Catch Extension Step](https://docs.shopgate.com/shopping-apps/references/connect/extensions/pipeline/error-catch-extension-step/): Error handling.
- [Step Context: Overview](https://docs.shopgate.com/shopping-apps/references/connect/extensions/steps/overview/): The `context` object passed to every step.
- [Step Context: Storage](https://docs.shopgate.com/shopping-apps/references/connect/extensions/steps/storage/): Extension/device/user storage.
- [Step Context: Logger](https://docs.shopgate.com/shopping-apps/references/connect/extensions/steps/logger/): Logging from steps.
- [Step Context: Meta](https://docs.shopgate.com/shopping-apps/references/connect/extensions/steps/meta/): Request metadata.
- [Step Context: App Info](https://docs.shopgate.com/shopping-apps/references/connect/extensions/steps/app-info/): App identifiers.
- [Step Context: Device Info](https://docs.shopgate.com/shopping-apps/references/connect/extensions/steps/device-info/): Device data.
- [Platform SDK Reference](https://docs.shopgate.com/shopping-apps/references/connect/platform-sdk/overview/): All `sgconnect` commands (`init`, `login`, `extension`, `backend`, `frontend`, `theme`).

## Frontend reference (Engage)

- [Portals Reference](https://docs.shopgate.com/shopping-apps/references/engage/portals/): Every available portal, grouped by screen (AppBar, Cart, Category, Product Details, Search, Tabbar, NavMenu, Filters, Favorites, Login, CMS pages).
- [Actions Reference](https://docs.shopgate.com/shopping-apps/references/engage/actions/overview/): Redux actions per domain (cart, category, checkout, favorites, modal, page, product, review, router, search, user).
- [Selectors Reference](https://docs.shopgate.com/shopping-apps/references/engage/selectors/overview/): Selectors per domain.
- [Streams Reference](https://docs.shopgate.com/shopping-apps/references/engage/streams/overview/): All app event streams.
- [Routes Reference](https://docs.shopgate.com/shopping-apps/references/engage/routes/overview/): Built-in routes and their patterns.
- [Hooks Reference](https://docs.shopgate.com/shopping-apps/references/engage/hooks/): React hooks provided by the theme.
- [HOCs Reference](https://docs.shopgate.com/shopping-apps/references/engage/hocs/): Higher-order components.
- [Components Reference](https://docs.shopgate.com/shopping-apps/references/engage/components/link/): Shared UI components (Link, Slider, I18n).
- [Theme Reference](https://docs.shopgate.com/shopping-apps/references/engage/theme/overview/): Theme structure, AppBar and View.
- [Tracking Events](https://docs.shopgate.com/shopping-apps/references/engage/tracking-events/): Every event a tracking extension can register for, with example payloads.
- [CMS Widget Configs](https://docs.shopgate.com/shopping-apps/references/cms/widget-configs/): Widget configuration format.
- [CMS Input Types](https://docs.shopgate.com/shopping-apps/references/cms/input-types/): Available merchant-facing input types.
- [Native Modules Overview](https://docs.shopgate.com/shopping-apps/references/native-modules/native-modules-overview/): Bridge to native functionality (camera, geolocation, push, keychain, sharing, in-app browser, status bar, splash screen, brightness, connectivity, app permissions, Android navigation bar) and third-party SDKs (Braze, Emarsys, Firebase Analytics, Facebook Analytics).

## Shopping App pipeline APIs (OpenAPI-generated)

- [Cart Pipelines](https://docs.shopgate.com/shopping-apps/api/cart/): Pipelines used by the default cart.
- [Product Pipelines](https://docs.shopgate.com/shopping-apps/api/product/): Product and filter pipelines.
- [Category Pipelines](https://docs.shopgate.com/shopping-apps/api/category/): Category and highlight pipelines.
- [User Pipelines](https://docs.shopgate.com/shopping-apps/api/user/): Login, registration, addresses.
- [Favorite Pipelines](https://docs.shopgate.com/shopping-apps/api/favorite/): Wishlist pipelines.
- [Review Pipelines](https://docs.shopgate.com/shopping-apps/api/review/): Product review pipelines.
- [CMS Pipelines](https://docs.shopgate.com/shopping-apps/api/cms/): CMS page pipelines.
- [CMS Service API](https://docs.shopgate.com/shopping-apps/api/cms-service-api/): Content delivery service for the apps.
- [Web Checkout API](https://docs.shopgate.com/shopping-apps/api/web-checkout-api/): Cart handover endpoints for web checkout.

## Omnichannel Suite

- [Welcome](https://docs.shopgate.com/omnichannel/welcome/): Entry point for the Omnichannel Suite.
- [Authentication](https://docs.shopgate.com/omnichannel/api-reference/general/authentication/): OAuth2 password and refresh_token grants against `https://auth.shopgate.io/oauth/token`.
- [Service URLs](https://docs.shopgate.com/omnichannel/api-reference/general/service-urls/): URL scheme `https://{serviceName}.shopgate.io/v{version}/merchants/{merchantCode}/{entity}`.
- [Batch Routes](https://docs.shopgate.com/omnichannel/api-reference/general/batch-routes/): Creating entities in batches.
- [Sorting, Filtering and Fields](https://docs.shopgate.com/omnichannel/api-reference/general/sorting-and-filtering/): Query conventions shared by all services.
- [Catalog: Concepts and Entities](https://docs.shopgate.com/omnichannel/guides/integrations/catalog/concepts-and-entities/): Data model of the catalog service.
- [Catalog: General Integration Info](https://docs.shopgate.com/omnichannel/guides/integrations/catalog/general-integration-info/): How to plan a catalog integration.
- [Catalog: Near-Realtime Import](https://docs.shopgate.com/omnichannel/guides/integrations/catalog/near-realtime-import/): Incremental updates.
- [Catalog: Bulk File Import](https://docs.shopgate.com/omnichannel/guides/integrations/catalog/bulk-file-import/): JSON bulk import.
- [Catalog: CSV Import](https://docs.shopgate.com/omnichannel/guides/integrations/catalog/csv-import/): CSV import format.
- [Order Integration Overview](https://docs.shopgate.com/omnichannel/guides/integrations/order/overview/): Sales orders, fulfillment orders, returns, picking.
- [Webhooks Overview](https://docs.shopgate.com/omnichannel/guides/integrations/webhook/overview/): Subscribing to events.
- [Available Webhooks](https://docs.shopgate.com/omnichannel/guides/integrations/webhook/available-webhooks/): The full event list.
- [Notifications](https://docs.shopgate.com/omnichannel/guides/integrations/notifications/): Customer notifications.
- [Segmentation](https://docs.shopgate.com/omnichannel/guides/integrations/segmentation/): Customer segments.
- [PHP SDK](https://docs.shopgate.com/omnichannel/guides/integrations/php-sdk/): Official PHP client.

## Omnichannel REST APIs (OpenAPI-generated)

- [Catalog Service](https://docs.shopgate.com/omnichannel/api/catalog/): Products, categories, attributes, inventory, reservations, exports.
- [Customer Service](https://docs.shopgate.com/omnichannel/api/customer/): Customers, contacts, devices, wishlists, segments.
- [Order Service](https://docs.shopgate.com/omnichannel/api/order/): Sales orders, fulfillment orders, picking batches, returns.
- [Import Service](https://docs.shopgate.com/omnichannel/api/import/): Bulk imports and import logs.
- [Webhook Service](https://docs.shopgate.com/omnichannel/api/webhook/): Webhook subscriptions.

## Support

- [FAQ](https://docs.shopgate.com/shopping-apps/support/faq/): Frequently asked developer questions.
- [Contact](https://docs.shopgate.com/shopping-apps/support/contact/): How to reach Shopgate support.

## Optional

- [Category XML Reference](https://docs.shopgate.com/shopping-apps/references/cart-integration/catalog-data-feed/category-xml/): Legacy catalog feed format.
- [Product XML Reference](https://docs.shopgate.com/shopping-apps/references/cart-integration/catalog-data-feed/product-xml/): Legacy catalog feed format.
- [Review XML Reference](https://docs.shopgate.com/shopping-apps/references/cart-integration/catalog-data-feed/review-xml/): Legacy catalog feed format.
- [Integrate External Notification Trigger](https://docs.shopgate.com/shopping-apps/integrate-external-notification-trigger/): Triggering push from outside.