Command Palette

Search for a command to run...

Integration Module Provider

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.

What Is an Integration Module Provider

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.


Creating a Custom Integration Module Provider

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:

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 { AbstractIntegrationProviderService } from "@gorgo/medusa-integration"
2
3class MyIntegrationProvider extends AbstractIntegrationProviderService {
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

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.


Registering Integration Module Providers

Configuring the Integration Module's Providers

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.

Registration on Application Start

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.

Registration Errors

Medusa stops the application at startup when a entry breaks one of these rules, and the error names the problem:

  • Two entries have the same identifier and the same , which includes two entries without an . The error is , with the identifier in place of .
  • A service class has no . The error is , where is the service's , or the path of the provider module when the service has none.
  • A provider module's default export lists no service. The error is , where is the entry's value.

Give every instance of a provider its own to avoid the first error. Refer to General Concepts for how the builds the key.

The Data Model

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

Warning: 

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.

Removing an Integration Module Provider

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.

Warning: 

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:

  • Put the old entry back, delete the integration from the Admin, and only then remove the entry or change it to the new .
  • Run from your code with the old key as . It doesn't need the provider to be registered, so it deletes the settings stored under that key, and you can configure the integration again under the new one.

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.

References

Edited Nov 12, 2026·Edit this page