In this document, you'll learn what an Integration Module Provider is, what it takes to implement one, how the module registers it at application start, and how the data model 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 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. Refer to General Concepts for the full range of cases.
Every provider registered in the Integration Module's option is represented in the database by the data model.
An Integration Module Provider is a module whose service extends , imported from . As with other Medusa module providers, a single module can register more than one Integration Module Provider service, each with its own , and each ends up as a separate provider.
declares the following members:
| Member | Description |
|---|---|
| Required. The provider's stable identifier, shared by every instance of it. | |
| Required, abstract. Returns the descriptor built with : the options, sections, validation, and optional connection test. | |
| Optional. A fail-fast check of the provider's configuration at load time. No-op by default. | |
| Implemented by the base class. Returns the class's . | |
| Implemented by the base class. Returns this instance's registration , taken from the constructor's argument, or for the default instance. |
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.ts1import { AbstractIntegrationProviderService } from "@gorgo/medusa-integration"23class MyIntegrationProvider extends AbstractIntegrationProviderService {4 static identifier = "my"56 static validateOptions(options: Record<string, unknown>) {7 // optional fail-fast check8 }910 get descriptor() {11 return descriptor12 }13}1415export default MyIntegrationProvider
here is whatever returns. Refer to Integration Provider Descriptor for every field it accepts. and aren't shown, because already implements both. returns the class's , and returns the the module passes as the constructor's third argument. A subclass therefore only adds , , and, optionally, .
If a subclass has its own constructor, it must pass all three arguments, , , and , to . Otherwise returns , even for a named instance.
is the former name of . The package still exports it as a deprecated alias, keeps it through every 2.x release and removes it in 3.0.
Refer to How to Create an Integration Module Provider for a full walkthrough with code.
The Integration Module accepts a option, where you configure the providers registered in your application, alongside the option used for the module's secret fields. Refer to How to Create an Integration Module Provider for the exact shape.
When the Medusa application starts, the Integration Module registers every provider listed in its option. Medusa first checks each entry's and . Then the module calls the provider's with the entry's and combines the class's with the entry's own into the key , the same format used for that instance's in the database. It registers the provider in the module's container under that key, and the container creates the instance with .
The steps run in this order for every entry:
A failed check or stops the application at startup, so a broken entry never reaches the key. An entry that passes becomes an instance in the module's container, and the Admin lists every registered instance, configured or not, under Settings → Integrations.
Once every provider is registered, the module logs a warning for each option whose name looks like a credential but isn't marked . Refer to Integration Provider Descriptor for how the module handles secrets.
Medusa stops the application at startup when a entry breaks one of these rules, and the error names the problem:
Give every instance of a provider its own to avoid the first error. Refer to General Concepts for how the builds the key.
A registered Integration Module Provider's instance is represented by the data model in the Medusa application.
The model's own is its internal record id, generated like on any other Medusa data model. It is not the same as , the column that actually holds the key from Identifiers and Instances.
The record holds the instance's , its , the store admin's settings in with secret options encrypted, the flag, and the result of the last connection test. The module creates the record on the first save of any section, so a registered provider without a record shows as Not configured in the Admin. Refer to Integration Module Data Models for every property.
The change history of the instance lives in a separate data model, , which isn't related to and outlives it. Refer to Settings Change History for what it records.
You can remove a registered Integration Module Provider by deleting its entry from the option in . 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 row by . The integration disappears from the list in the Admin, and its stored data becomes unreachable through the Integration Module's own admin routes. Its records stay in the change history of all integrations.
Delete the integration from the Admin before removing the provider from , not after. Once the provider is gone from the config, its row can no longer be reached, including through the delete route itself, so it stays in the database with no way to remove it from the Admin. Refer to Manage Integrations in Medusa Admin for the normal deletion flow.
Changing an entry's , or the class's , has the same effect, because it changes the key . The new key has no stored row, so the instance shows as Not configured, and the settings stay in the database under the old key, out of reach of the Admin. You have two ways out:
Refer to Integration Module Workflows for the workflow's input and import path.
To stop a provider from being used while keeping its configuration intact, so you can bring it back later, disable it from the Admin instead of removing it from . Refer to Manage Integrations in Medusa Admin to learn how.