Skip to main content

Adding an integration

  1. Create src/integrations/<provider>. Keep the SDK import inside that folder.
  2. Marketplace classes must match the auto-registration regex. You need {Provider}OrderService and {Provider}CatalogService or the provider will not register. Optional capabilities use the same prefix: Customer, Settlement, OutboundOrder, Inventory, WebhookHealth. The provider token must be one of Shopify, WooCommerce, Amazon, Flipkart, BigCommerce, Meesho. A new marketplace name will not match until that regex is updated.
  3. A courier class must expose integrationCode, ship, cancel, and track.
  4. Add a registry seed entry if the connection hub should list it.
  5. Store secrets on IntegrationConnection through the vault, not on Channel.config.
  6. Webhooks are @PublicRoute. Verify a signature in the controller. Do not accept unsigned bodies because another provider does. WhatsApp fails closed when META_APP_SECRET is unset. Follow that unless you have a reason not to.
  7. Long work goes to webhook_queue or a dedicated queue. Do not hold the HTTP request for a full catalog import.
  8. If you publish inventory, decide whether you need a flush-channel:<CODE> job or DEFAULT.
  9. If sync should participate in the circuit breaker, go through SyncJobProcessorWorker rather than a private loop.

CUSTOM is not a pattern to copy for a real channel. The scheduler skips unknown types.

See Integrations overview.