Business configuration

Based on the businessConfig schema that you defined in the app.commerce.config, the configuration library generates the runtime actions that the App Management UI uses to render a configuration form with no custom code required.

See Initialize your app for setup instructions and Build and deploy for information about generated runtime actions and project structure.

Example

The following example shows a complete configuration schema with various field types:

import { defineConfig } from "@adobe/aio-commerce-lib-app/config"

export default defineConfig({
  businessConfig: {
    schema: [
      {
        name: "api-name",
        label: "API name",
        type: "text",
        default: "",
      },
      {
        name: "api-endpoint",
        label: "API Endpoint",
        type: "url",
        default: "https://api.example.com",
      },
      {
        name: "api-key",
        label: "API Key",
        type: "password",
      },
      {
        name: "level",
        label: "Risk Level",
        type: "list",
        options: [
          { label: "Low", value: "low" },
          { label: "Medium", value: "medium" },
          { label: "High", value: "high" },
        ],
        default: "medium",
        selectionMode: "single",
      },
    ],
  },
});
Copied to your clipboard
import { defineConfig } from "@adobe/aio-commerce-lib-app/config"

export default defineConfig({
  businessConfig: {
    schema: [
      {
        name: "api-name",
        label: "API name",
        type: "text",
        default: "",
      },
      {
        name: "api-endpoint",
        label: "API Endpoint",
        type: "url",
        default: "https://api.example.com",
      },
      {
        name: "api-key",
        label: "API Key",
        type: "password",
      },
      {
        name: "level",
        label: "Risk Level",
        type: "list",
        options: [
          { label: "Low", value: "low" },
          { label: "Medium", value: "medium" },
          { label: "High", value: "high" },
        ],
        default: "medium",
        selectionMode: "single",
      },
    ],
  },
});

Rendered schema

Schema properties

This businessConfig schema contains the following properties:

Property	Type	Required	Description
`name`	string	Yes	Unique field identifier. Used to retrieve values at runtime.
`label`	string	Yes	Display label of a configuration field.
`type`	string	Yes	Field type. See Supported types.
`default`	varies	No	Default value. Must match the field type.
`description`	string	No	Help text displayed below the field.
`options`	array	Conditional	Required for `list`. Defines available options to be displayed in the dropdown list.
`selectionMode`	string	Conditional	Required for `list`. Set to `single` for standard dropdown or `multiple` to allow multiple selections.

Supported field types

The following field types are available for your businessConfig schema:

Field type	Type	Description
`text`	string	Single-line text input
`password`	string	Masked input for sensitive values like API keys and tokens. See Password field encryption.
`email`	string	Email address input with validation
`tel`	string	Phone number input with format validation
`url`	string	URL input with validation
`list`	string	Dropdown with preconfigured options

Password field encryption

Password fields are automatically encrypted using AES-256-GCM when stored and decrypted when retrieved.

To validate that your encryption key is properly configured, run:

npm

yarn

pnpm

bun

npx aio-commerce-lib-config encryption validate
Copied to your clipboard
npx aio-commerce-lib-config encryption validate

yarn exec aio-commerce-lib-config encryption validate
Copied to your clipboard
yarn exec aio-commerce-lib-config encryption validate

pnpm exec aio-commerce-lib-config encryption validate
Copied to your clipboard
pnpm exec aio-commerce-lib-config encryption validate

bun x aio-commerce-lib-config encryption validate
Copied to your clipboard
bun x aio-commerce-lib-config encryption validate

This command is executed automatically during the pre-app-build hook.

To manually generate an encryption key, use:

npm

yarn

pnpm

bun

npx aio-commerce-lib-config encryption setup
Copied to your clipboard
npx aio-commerce-lib-config encryption setup

yarn exec aio-commerce-lib-config encryption setup
Copied to your clipboard
yarn exec aio-commerce-lib-config encryption setup

pnpm exec aio-commerce-lib-config encryption setup
Copied to your clipboard
pnpm exec aio-commerce-lib-config encryption setup

bun x aio-commerce-lib-config encryption setup
Copied to your clipboard
bun x aio-commerce-lib-config encryption setup

This generates a secure 256-bit encryption key and adds AIO_COMMERCE_CONFIG_ENCRYPTION_KEY to your .env file.

Never commit the .env file to version control. Keep the encryption key secure and only accessible in the app runtime context. Operations fail if the key is not configured. Passwords are never stored in plain text.

See Password Field Encryption for more information.

See Failed to decrypt configuration if you already see decrypt errors.

Multiple selection list fields

For fields that allow multiple selections, set selectionMode to multiple and the default value must be an array of strings, even if only one option is selected by default.

{
  name: "paymentMethods",
  label: "Enabled Payment Methods",
  type: "list",
  selectionMode: "multiple",
  options: [
    { label: "Credit Card", value: "credit_card" },
    { label: "PayPal", value: "paypal" },
    { label: "Apple Pay", value: "apple_pay" },
  ],
  default: ["credit_card"]
}
Copied to your clipboard
{
  name: "paymentMethods",
  label: "Enabled Payment Methods",
  type: "list",
  selectionMode: "multiple",
  options: [
    { label: "Credit Card", value: "credit_card" },
    { label: "PayPal", value: "paypal" },
    { label: "Apple Pay", value: "apple_pay" },
  ],
  default: ["credit_card"]
}

Scope tree synchronization

Apps with businessConfig use a scope tree (Global, Commerce websites, stores, and store views) when merchants configure settings in App Management. That tree reflects Adobe Commerce scope structure as of the last sync. It is not kept in lockstep with Commerce automatically.

Commerce scope changes require a manual sync per app

When you add, rename, or remove websites, stores, or store views in Adobe Commerce, App Management does not refresh the scope hierarchy by itself. Cached scope data is used until an Admin runs Sync commerce scopes for that application.

If several apps are associated with the same instance—for example, ten apps that define business configuration—you must open each app in App Management and sync individually. From the application, open Manage scopes, open Quick actions, then choose Sync commerce scopes.

Removing scopes

After a scope is deleted in Commerce, run Sync commerce scopes again for each affected application. The operation replaces the cached tree with the current Commerce data, so scopes that no longer exist in Commerce disappear from App Management after a successful sync.

Manage Scopes Quick actions menu with Sync commerce scopes

Schema requirements

Your app.commerce.config is validated each time you run a generate command (for example, npx aio-commerce-lib-app generate all). The schema validation checks for:

Required properties. Fields must have name, label, and type.
Type-matched defaults. Default values must match the field type (for example, a text field cannot have a number default).
Encryption key for passwords. If your schema contains password fields, configure an encryption key. See Password field encryption for more information.

Retrieve configuration at runtime

Use getConfigurationByKey from the configuration library to access configuration values in your runtime actions:

import { getConfigurationByKey, byCodeAndLevel } from "@adobe/aio-commerce-lib-config";

async function main(params) {
  const storeCode = params.store_code || "default";
  const storeLevel = params.store_level || "store_view";

  // Use values in your app logic
  const { config: { value: endpoint } } = await getConfigurationByKey("api-endpoint", byCodeAndLevel(storeCode, storeLevel));
  const { config: { value: apiKey } } = await getConfigurationByKey("api-key", byCodeAndLevel(storeCode, storeLevel), {
    encryptionKey: params.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY,
  });
}
Copied to your clipboard
import { getConfigurationByKey, byCodeAndLevel } from "@adobe/aio-commerce-lib-config";

async function main(params) {
  const storeCode = params.store_code || "default";
  const storeLevel = params.store_level || "store_view";

  // Use values in your app logic
  const { config: { value: endpoint } } = await getConfigurationByKey("api-endpoint", byCodeAndLevel(storeCode, storeLevel));
  const { config: { value: apiKey } } = await getConfigurationByKey("api-key", byCodeAndLevel(storeCode, storeLevel), {
    encryptionKey: params.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY,
  });
}