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",
      },
    ],
  },
});

Schema properties

This businessConfig schema contains the following properties:

Supported field types

The following field types are available for your businessConfig schema:

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:

data-slots=heading, code

data-repeat=4

data-languages=BASH, BASH, BASH, BASH

npx aio-commerce-lib-config encryption validate

yarn exec aio-commerce-lib-config encryption validate

pnpm exec aio-commerce-lib-config encryption validate

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:

data-slots=heading, code

data-repeat=4

data-languages=BASH, BASH, BASH, BASH

npx aio-commerce-lib-config encryption setup

yarn exec aio-commerce-lib-config encryption setup

pnpm exec aio-commerce-lib-config encryption setup

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.

data-variant=warning

data-slots=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"]
}

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.

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 (together with getConfiguration and setConfiguration when you need full documents or writes) to access configuration values in your runtime actions.

Before you run getConfiguration, getConfigurationByKey, or setConfiguration, call initialize with your generated configuration schema. The schema is kept in memory for that action invocation. Import the generated configuration-schema.json from your commerce/configuration/1 extension (the path relative to your action depends on your project layout).

If you skip initialize, see Initialization in the configuration library usage guide for more information.

A scope selector tells the library which node in the scope tree to read or write. That tree can include Adobe Commerce scopes (such as websites and store views, each with a scope code and a level in the hierarchy), custom scopes you create in App Management (code only; see below), global scope, and other nodes that your app or merchants configure.

When the target scope has both a code and a level, which is typical for Commerce store and website scopes, use byCodeAndLevel.

The following examples show only the configuration calls. In your action, run initialize before these calls. For a full runtime action example, see Using configuration in runtime actions in the usage guide.

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,
  });
}

Custom scopes created in the App Management UI are identified by code only. They do not define a separate level in the tree. For those scopes you must use byCode("your-custom-scope-code"). byCodeAndLevel is not used for custom scopes because there is no level to pass. See the configuration library usage for more information.

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

const { config: { value: endpoint } } = await getConfigurationByKey(
  "api-endpoint",
  byCode("your-custom-scope-code"),
);

Global scope and selectors

getConfiguration, getConfigurationByKey, and setConfiguration accept an optional scope selector. When you omit it, the library resolves the global scope.

For more patterns and API detail, see the configuration library usage documentation in the Adobe Commerce SDK repository.

Tutorial

Watch this video to learn how to define a configuration schema and see the auto-generated Admin UI in action.

Configuration schema tutorial