In this guide you'll learn about the Integration Module Provider: what it is, what it takes to implement one, how the module registers it at application start, and the Integration data model that represents each registered instance in the database.

An Integration Module Provider declares an integration: its options, how they group into settings sections, and an optional connection test. A store admin configures it in the Admin, with no medusa-config edits and no redeploy.

The Integration Module is provider-agnostic, so unlike Medusa's built-in commerce modules, it ships no default or placeholder provider of its own. Any plugin, provider, or custom module can be an Integration Module Provider. See Where It Can Be Used for the full range of cases.

Every provider registered in the Integration Module's providers option is represented in the database by the Integration data model.

An Integration Module Provider is a module whose service extends AbstractIntegrationProvider, imported from @gorgo/medusa-integration. As with other Medusa module providers, a single module can register more than one Integration Module Provider service, each with its own static identifier, and each ends up as a separate provider.

AbstractIntegrationProvider declares the following members:

Here's the shape of a minimal provider, with every member from the table above in place except the ones the base class already implements:

providers/integration-my/services/my-integration.ts
1import { AbstractIntegrationProvider } from "@gorgo/medusa-integration"
2
3class MyIntegrationProvider extends AbstractIntegrationProvider {
4  static identifier = "my"
5
6  static validateOptions(options: Record<string, unknown>) {
7    // optional fail-fast check
8  }
9
10  get descriptor() {
11    return descriptor
12  }
13}
14
15export default MyIntegrationProvider

descriptor here is whatever defineIntegration returns, covered in General Concepts. getIdentifier() and getInstanceId() aren't shown: AbstractIntegrationProvider already implements both from the constructor's instanceId argument, so a subclass only adds static identifier, descriptor, and, optionally, static validateOptions.

The Integration Module accepts a providers option, where you configure the providers registered in your application, alongside the encryptionKey option used for the module's secret fields. See step 4 of How to Create an Integration Module Provider for the exact medusa-config.ts shape.

When the Medusa application starts, the Integration Module registers every provider listed in its providers option. For each entry, it combines the provider class's static identifier with the entry's own id into the key int_<identifier>[_<id>], the same format used for that instance's provider_id in the database, then constructs the provider with new ProviderClass(container, options, instanceId).

A registered Integration Module Provider's instance is represented by the Integration data model in the Medusa application.

You can remove a registered Integration Module Provider by deleting its entry from the providers option in medusa-config.ts. Unlike disabling an integration from the Admin, this doesn't touch the stored row. It only stops the provider from being registered, so the module can no longer look up its Integration row by provider_id. The integration disappears from the list in the Admin, and its stored data becomes unreachable through the Integration Module's own admin routes.

To stop a provider from being used while keeping its configuration intact and easy to bring back, disable it from the Admin instead of removing it from medusa-config.ts. See Enable and Disable an Integration.