Command Palette

Search for a command to run...

How to Create an Integration Module Provider

In this guide, you'll learn how to create a Medusa provider that manages its settings through the Integration Module.

What is the Integration Module? 

The Integration Module lets any plugin describe its options as a schema, and store admins configure them in the Admin, with no edits and no redeploy of the Medusa app. It generates the UI, provides a CRUD API and validation, so you don't have to write your own data models, routes, forms, or workflows.

The diagram shows what this guide builds and how the parts connect:

registers the provider definition, which is the file that calls . The definition declares the service class, which has a and a . The Integration Module turns the descriptor into the page under Settings → Integrations, where the store admin fills in the options. Your code then reads them with .

Implementation Example

When you write your own Integration Module provider, it helps to see how a finished one is put together.

For a real implementation, read the YooKassa payment provider in the Medusa Integrations repository.


1. Create the Provider Directory

Start by creating a new directory for your Integration Module provider. In a plugin it goes under , for example .

If you don't have a plugin yet, create one together with an example project using .


2. Create the Integration Module Provider Service

Create the file , which declares the integration provider's descriptor and the service itself.

Directory structure in the Medusa plugin after creating the service file

providers/integration-my/services/my-integration.ts
1import {
2 AbstractIntegrationProviderService
3} from "@gorgo/medusa-integration"
4
5class MyIntegrationProvider extends AbstractIntegrationProviderService {
6 // TODO add methods
7}
8
9export default MyIntegrationProvider

The parent class you're extending here, , is abstract, so the subclass must implement its property (declared as a ). The class also needs a , which the loader relies on.

identifier

Every Integration Module provider has a unique identifier. The store admin configures the provider under it, and a consumer reads the provider's options by the same one.

Pick an identifier no other provider uses. When two providers declare the same one, the module logs a warning at startup that names both of them, and from version 3.0 it refuses to start.

Example

providers/integration-my/services/my-integration.ts
1class MyIntegrationProvider extends AbstractIntegrationProviderService {
2 static identifier = "my"
3 // ...
4}

The loader reads this static field to build the key your instance is registered under: , or without an ID.

descriptor

The provider class must implement the property. The descriptor holds a single declaration of the options, how they group into settings sections, and an optional connection test. You create it with .

Refer to General Concepts for an overview of the descriptor, and to Integration Provider Descriptor for the full reference of every field (, , , , , , , and others), by type. Validate Integration Options covers the rules you can declare, and Localize an Integration covers the translations for the i18n keys.

Example

providers/integration-my/services/my-integration.ts
1import {
2 AbstractIntegrationProviderService,
3 defineIntegration,
4 z
5} from "@gorgo/medusa-integration"
6
7const descriptor = defineIntegration({
8 category: "payment",
9 displayName: "my.name",
10 options: {
11 apiKey: {
12 type: "string",
13 control: "secret",
14 secret: true,
15 required: true,
16 minLength: 1,
17 label: "my.apiKey"
18 },
19 sandbox: {
20 type: "boolean",
21 control: "switch",
22 default: false,
23 label: "my.sandbox"
24 },
25 },
26 sections: [
27 {
28 id: "credentials",
29 title: "my.credentials",
30 options: ["apiKey", "sandbox"]
31 },
32 ],
33})
34
35export type MyOptions = z.infer<typeof descriptor.optionsSchema>
36
37export class MyIntegrationProvider extends AbstractIntegrationProviderService {
38 // ...
39 get descriptor() {
40 return descriptor
41 }
42}
43
44export default MyIntegrationProvider

is the resolved, validated shape: builds from the object, and since is and has a , both end up non-optional in .

A option of type accepts an empty string, so also sets . An empty key then fails validation, and the integration stays incomplete until the admin enters a value. Refer to Validate Integration Options to learn about the rules you can declare.

validateOptions

Like other Medusa providers, an Integration Module provider can declare a static to check its configuration at load time.

Example

providers/integration-my/services/my-integration.ts
1class MyIntegrationProvider extends AbstractIntegrationProviderService {
2 // ...
3 static validateOptions(options: Record<string, unknown>) {
4 // optional fail-fast check of options.providers[].options
5 }
6}

The base class's own is a no-op (), so overriding it is optional. The return type signals it either returns nothing or throws to fail the load.

In practice, is almost always for an Integration Module provider. The store admin sets the real settings in the Admin rather than in , so matters less here than it does for other Medusa providers.

testConnection

Unlike , which checks the provider's configuration in , checks the integration's own options, such as an API key, against the third-party service. The store admin runs it from the Admin, and a scheduled job re-tests every enabled integration once a day. You declare it directly in the descriptor.

Example

providers/integration-my/services/my-integration.ts
1const descriptor = defineIntegration({
2 // ...
3 testConnection: async ({ options }) => {
4 const res = await fetch("https://api.my.com/ping", {
5 headers: { Authorization: `Bearer ${options.apiKey}` },
6 })
7
8 return res.ok
9 ? { status: "passed" }
10 : { status: "failed", message: `My responded with ${res.status}` }
11 },
12})

is one of . Returning counts as a normal result, not an error. If throws, the module reports the test as with the error's message, so the store admin sees it in the Admin either way.


3. Create Module Provider Definition File

Create the file with the following content:

Directory structure in the Medusa plugin after creating the provider definition file

providers/integration-my/index.ts
1import { ModuleProvider } from "@medusajs/framework/utils"
2import { INTEGRATION_MODULE } from "@gorgo/medusa-integration"
3import MyIntegrationProvider from "./services/my-integration"
4
5export default ModuleProvider(INTEGRATION_MODULE, {
6 services: [MyIntegrationProvider],
7})

This exports the provider definition, declaring as its service.


4. Register the Provider

To use your Integration Module provider, add it to the Integration Module's array in , and list the plugin itself in . Replace with the in your plugin's :

medusa-config.ts
1module.exports = defineConfig({
2 // ...
3 plugins: [
4 {
5 resolve: "@gorgo/medusa-integration",
6 options: {
7 encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
8 providers: [
9 {
10 resolve: "<your-plugin-package>/providers/integration-my",
11 options: {},
12 },
13 ],
14 },
15 },
16 {
17 resolve: "<your-plugin-package>",
18 options: {},
19 },
20 // ...
21 ],
22})

The loader instantiates from the entry. Its is the plugin's package name followed by the provider's path, , which relies on the plugin's export in .

The second entry lists the plugin itself. Medusa loads a plugin's Admin extensions, such as its translations and widgets, only for packages listed in . Without the entry the provider still registers, but the Admin doesn't load the plugin's translations, so the integration page shows keys such as instead of readable text.

That value is for a provider in a plugin. A provider that sits inside the Medusa application itself is registered by its path from the application's directory, such as , and needs no entry in . Medusa resolves a relative path against the application's directory, so the same path fails for a provider in a plugin.

Warning: 

Leave out while your provider has a single instance, as in the example above. The provider then registers under the key , which is , and a consumer reads its options with . Add an only when you register the provider more than once, with one per instance. The key then becomes , for example , and a consumer has to pass the same value as . Otherwise throws, because nothing is registered under . Refer to Identifiers and Instances to learn how instances work.

Next, add the secret encryption key to your environment variables. The Integration Module uses it to encrypt secrets before saving them to the database:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

Any non-empty value works. The module derives it via SHA-256 into a 32-byte AES-256-GCM key, so use a high-entropy one, for example .


5. Test It Out

Start the server and open Settings → Integrations in Medusa Admin. Your integration appears in the list. Fill in the options, then choose Test connection in the action menu next to the integration's name to run .

To read the saved options, use and pass the same your provider class declares:

providers/payment-my/services/my-payment.ts
1import { resolveIntegrationOptions } from "@gorgo/medusa-integration"
2import type { MyOptions } from "../../integration-my/services/my-integration"
3
4const options = await resolveIntegrationOptions<MyOptions>({
5 identifier: "my",
6})

The returned is typed as , already decrypted and validated. By default the call throws a if the integration is not configured, disabled, or incomplete.

Refer to Reading Options to learn how to read an integration's options from a route, subscriber, or workflow step.

References

Edited Nov 12, 2026·Edit this page