An integration provider's descriptor is where you declare the integration's options, how they group into settings sections, their validation, and an optional connection test. This page is the full reference for every field you can put in one.
For the roles involved and how an option moves from the descriptor to a resolved value at runtime, see General Concepts.
Create a descriptor with . It builds from your catalog, used for , defaults, and full validation.
providers/integration-my/services/my-integration.ts1import { defineIntegration, AbstractIntegrationProviderService } from "@gorgo/medusa-integration"23const descriptor = defineIntegration({4 category: "payment",5 displayName: "my.name",6 options: {7 apiKey: {8 type: "string",9 control: "secret",10 secret: true,11 required: true,12 label: "my.apiKey"13 },14 sandbox: {15 type: "boolean",16 control: "switch",17 default: false,18 label: "my.sandbox"19 },20 },21 sections: [22 {23 id: "credentials",24 title: "my.credentials",25 options: ["apiKey", "sandbox"]26 },27 ],28})2930export class MyIntegration extends AbstractIntegrationProviderService {31 static identifier = "my"3233 get descriptor() {34 return descriptor35 }36}
This descriptor declares and , grouped into a single section. fails fast at load time in two cases: a section referencing an option id that isn't in , and an option whose mixes strings and numbers.
accepts the following properties:
The provider's isn't part of the descriptor. The module adds it from the provider class when it registers the provider.
Each entry of is a card on the integration's page, with its own Edit action. A section references options by id, and an option can stay out of every section, for example when a custom section edits it instead.
Each option in is an object shaped . The field determines the available values and the remaining fields that are common to every type:
Some types have extra fields on top of the common ones:
The module generates the CRUD API from the descriptor and validates every write. Validation covers per-option rules, such as types, ranges, and patterns, along with cross-section rules that span the whole configuration. There is nothing to build for each integration.
Refer to Validate Integration Options to learn when each rule runs and how to test the descriptor's rules, and to Admin API Routes for the generated routes.
Options become live only when the integration is both enabled and complete, meaning it passes full validation. An incomplete draft or a disabled integration never resolves, so half-finished configuration cannot leak into runtime.
Options marked are encrypted at rest with AES-256-GCM and never reach the browser. The CRUD API masks them and reports only whether each one is set. Saving a secret as blank keeps its stored value instead of clearing it.
doesn't select the control. Without , the Admin renders the option as a plain text input, so the value the store admin types is visible, and the field doesn't say that leaving it blank keeps the stored value. When the option is also , the Admin demands a value on every save of its section, so the store admin has to retype the stored secret each time. Set on every option.
Secret values don't reach the change history either. For a secret option, the history shows only that its value was set, replaced, or removed. It keeps the values of every other option as they are.
An option that holds a credential but isn't marked is shown in the Admin and kept in the change history in plain text. On startup, the module logs a warning for every option whose name looks like a credential but isn't marked . The warning is logged once per provider identifier, even when the provider is registered more than once. A name looks like a credential when it contains , , , , , or , in any letter case. and also match with an underscore or a hyphen between the words, such as or . The match is on part of the name, so and count, while and don't.
The module encrypts a secret value when it saves it, and decrypts it when it reads the integration. When you change an option's flag after a store admin has saved a value for it, the integration keeps working:
One case still fails. The module takes a stored string as encrypted when it starts with , or when it has the shape of a value encrypted by version 0.x of the module, which is standard base64 (, , , , , and as padding) at least 40 characters long, with a length that's a multiple of 4 and at least 29 bytes once decoded. A plain-text value of that shape under an option you've just marked doesn't decrypt, and reading the integration throws the error described in Integration Module Options. To recover, delete the stored settings with the route, then enter them again. To stay clear of it, decide whether an option is secret before a store admin saves a value for it.
Encryption needs a key, set as when you register the module. Refer to Integration Module Options to learn how to set it and what happens without one.
A descriptor can declare an optional connection test that checks credentials against the third-party service. Store admins run it on demand, and a scheduled job re-tests every enabled integration once a day, at 03:00 by the server's clock.
Add to the descriptor. It receives the already-resolved (decrypted) options and returns a status:
providers/integration-my/services/my-integration.ts1const descriptor = defineIntegration({2 // ...3 testConnection: async ({ options }) => {4 const res = await fetch("https://api.my.com/ping", {5 headers: { Authorization: `Bearer ${options.apiKey}` },6 })78 if (!res.ok) {9 return { status: "failed", message: `My responded with ${res.status}` }10 }1112 return { status: "passed" }13 },14})
is one of , , or . The module stores the status as the integration's and emits the event. It doesn't store , which only the event and the Admin notification carry.
When the status isn't , the Admin shows in a notification, or the status itself when there is no message. A result shows a fixed success notification, whatever holds.
The test runs only against options that resolve. When the integration isn't configured, is disabled, or is incomplete, the module reports with the message without calling . When throws, the module reports with the error's message. Refer to Integration Module Workflows to learn every result the module produces itself, including an unknown provider and a descriptor without .
Consumers read typed, validated, and decrypted options, with descriptor defaults applied. An incomplete or disabled integration resolves to nothing rather than partial data. Refer to Reading Options to learn the ways to read them and how long the module caches them.
Several descriptor fields take their value from a fixed list. These are , the and of an option, the of a section, , and the that returns. The lists change between versions of the module this way:
Code that branches on one of these values, such as a over , needs a branch for a value it doesn't know. Then a minor release of the module doesn't break it.
Default:
Default:
Default:
Default:
Default: