Command Palette

Search for a command to run...

Integration Provider Descriptor

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.

defineIntegration

Create a descriptor with . It builds from your catalog, used for , defaults, and full validation.

providers/integration-my/services/my-integration.ts
1import { defineIntegration, AbstractIntegrationProviderService } from "@gorgo/medusa-integration"
2
3const 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})
29
30export class MyIntegration extends AbstractIntegrationProviderService {
31 static identifier = "my"
32
33 get descriptor() {
34 return descriptor
35 }
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.


Descriptor Properties

accepts the following properties:

Loading...

The provider's isn't part of the descriptor. The module adds it from the provider class when it registers the provider.


Sections

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.

Loading...

Option Fields

Each option in is an object shaped . The field determines the available values and the remaining fields that are common to every type:

Loading...

Type-Specific Fields

Some types have extra fields on top of the common ones:

  • : , ,
  • :
  • : , , , , ,
  • : ,
Loading...

Generated CRUD and Validation

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.


Enabled and Complete

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.


Secrets and Encryption

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.

Warning: 

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.

Warning: 

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:

  • When you add , the module reads the stored plain-text value as it is, so the consumer, the connection test, and the Admin keep working. The next save of any section of the integration stores the value encrypted, because a save encrypts the whole merged configuration again.
  • When you remove , the module decrypts the stored value when it reads the integration. The consumer, the that returns, and the record in the change history get plain text, and the next save stores the value unencrypted. If the value doesn't decrypt, for example after a change of , the module returns the stored string as it is, without an error.

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.


Connection Test

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.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 if (!res.ok) {
9 return { status: "failed", message: `My responded with ${res.status}` }
10 }
11
12 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 .


Runtime Options Resolution

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.


Value Lists Across Versions

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:

  • A new value arrives in a minor release. A new category or connection test status also brings a migration, because the database checks the stored value against the list. Run after the upgrade to apply it.
  • A value is removed or renamed only in a major release.

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.

References

Edited Nov 12, 2026·Edit this page