commerce-app-business-config
Manage custom business configuration in an Adobe Commerce app. Use when the user wants to add, modify, or remove merchant-configurable settings (config fields, admin config, store configuration) exposed through Commerce Admin. Creates typed config fields (text, password, email, url, tel, boolean, list) in businessConfig.schema. Requires a base app initialized with commerce-app-init.
- Installs
- 80
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/adobe/aio-commerce-sdk --skill commerce-app-business-config- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads commerce-app-business-config automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Configure Commerce App Business Config
Adds or modifies the businessConfig.schema array in an existing app.commerce.config.ts.
Each entry in the schema defines one merchant-configurable setting that Commerce Admin will render as a UI field.
Other extensibility domains (webhooks, events) are added separately via their own skills.
Prerequisites
- Verify the app is scaffolded and initialized, not merely that the config exists. Require both:
app.commerce.config.tspresent in the project root, and- the project initialized — signalled by the generated
src/commerce-extensibility-1/directory and installednode_modules(the@adobe/aio-commerce-lib-appdependency).
- If
app.commerce.config.tsis missing, stop and invokecommerce-app-initfirst (it writes the config, then runs init). - If the config is present but the project is not initialized (no
src/commerce-extensibility-1/ornode_modules), runnpx @adobe/aio-commerce-lib-app initbefore continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
Step 1 — Understand intent
For each setting the user wants to expose, gather:
- Name — machine identifier for the field (used as the config key read by the app at runtime)
- Type — one of:
list,text,password,email,url,tel,boolean - Label (optional) — human-readable label shown in Admin
- Description (optional) — help text shown alongside the field in Admin
- Default value (optional, type-dependent — see constraints in Step 2)
- For
listfields additionally:selectionMode("single"or"multiple") andoptions(each with alabelandvaluestring)
Step 2 — Derive config values
Apply the following per-type validation rules before writing. Surface any issues to the user before proceeding.
| Field | Constraint |
|---|---|
name | Required, non-empty string |
type | Required; one of list, text, password, email, url, tel, boolean |
label | Optional string |
description | Optional string |
list.selectionMode | Required for list fields: "single" or "multiple" |
list.options | Required for list fields; each option needs both label and value strings |
list/single default | Required; must match one of the option value strings (non-empty) |
list/multiple default | Optional array of strings (defaults to []); each element must match an option value |
text default | Optional string (defaults to "") |
password default | Must be "" — any non-empty default is rejected to prevent secrets in config |
email default | Optional; "" or a fully valid email address |
url default | Optional; "" or a fully valid absolute URL |
tel default | Optional; "" or matches /^\+?[0-9\s\-()]+$/ (digits, spaces, hyphens, parens, optional +) |
boolean default | Optional boolean (defaults to false) |
businessConfig.schema must contain at least one field — an empty array is rejected at build time.
Step 3 — Update app.commerce.config.ts
Add (or merge into) the top-level businessConfig.schema array, preserving all other domains. If the config already has a businessConfig key, append to businessConfig.schema rather than replacing it.
Minimal examples:
businessConfig: {
schema: [
// Password (masked input — API keys, secrets)
{ name: "api_key", type: "password", label: "API Key", default: "" },
// Single-select list
{
name: "region", type: "list", selectionMode: "single",
label: "Region",
options: [{ label: "EU", value: "eu" }, { label: "US", value: "us" }],
default: "eu", // required; must match an option value
},
// Boolean toggle
{ name: "debug_mode", type: "boolean", label: "Enable Debug Mode", default: false },
// Dynamic list — options resolved at runtime via a factory that receives the action's params.
// Required `default` factory for single-select; optional for multiple (falls back to []).
{
name: "paymentMethod", type: "dynamicList", selectionMode: "single",
label: "Default Payment Method",
options: async (params) => {
const methods = await fetchPaymentMethods(params.SOME_API_KEY);
return methods.map((m) => ({ label: m.title, value: m.code }));
},
default: (resolvedOptions) => resolvedOptions[0].value,
},
],
}
See assets/business-config.ts for the full reference showing all field types.
Step 4 — Register the extension point
Run init so that commerce/configuration/1 is added to app.config.yaml and install.yaml, and the required @adobe/aio-commerce-lib-config dependency is installed. This is idempotent — safe to run even if the extension is already registered.
npx @adobe/aio-commerce-lib-app init
Step 5 — Validate
Build the project to confirm the updated config is valid:
aio app build
A build failure with a validation error points directly to the offending field.
Reading config in runtime actions
Use @adobe/aio-commerce-lib-config to read the values merchants set in Commerce Admin.
The library must be initialized with the generated schema on every action invocation before any config call.
Basic pattern
import {
initialize,
getConfigurationByKey,
getConfiguration,
byCodeAndLevel,
} from "@adobe/aio-commerce-lib-config";
// Schema is generated by `aio app build` into .generated/configuration-schema.json
// under the commerce-configuration-1 extension; adjust the relative path for your action.
import schema from "../../.generated/configuration-schema.json" with { type: "json" };
export async function main(params) {
await initialize({ schema });
// Read a single field — config is null if the key has never been set
const { config } = await getConfigurationByKey(
"api_key", // the `name` from your schema
byCodeAndLevel("global", "global"), // scope
);
const apiKey = config?.value ?? "";
// Read all fields for a scope
const { config: allConfig } = await getConfiguration(
byCodeAndLevel("global", "global"),
);
// allConfig is an array of { name, value, origin } entries
return { statusCode: 200, body: { success: true } };
}
Scope selectors
| Selector | When to use |
|---|---|
byCodeAndLevel("global", "global") | App-wide settings — applies to all stores |
byCodeAndLevel(storeCode, "store_view") | Per store view (most specific) |
byCode(storeCode) | Resolves using the default level for the scope |
byScopeId(scopeId) | When you have the scope's numeric ID from Commerce |
Values inherit from parent scopes — a field not set on store_view falls back to store, website, then global.
Password fields
aio app build generates AIO_COMMERCE_CONFIG_ENCRYPTION_KEY automatically into .env the first time it encounters a password field (and validates it on subsequent builds). No manual setup needed.
To decrypt values at runtime, the key must be available to the action. Wire it as an input in the action's ext.config.yaml:
inputs:
AIO_COMMERCE_CONFIG_ENCRYPTION_KEY: $AIO_COMMERCE_CONFIG_ENCRYPTION_KEY
With the key in place, getConfigurationByKey returns the plaintext value — no extra decryption code needed.
Common Issues
list/singledefault missing: Single-select list fields require adefault— it can't be omitted. It must exactly match one of the optionvaluestrings.defineConfignot found: Ensure@adobe/aio-commerce-lib-appis installed anddefineConfigis imported from@adobe/aio-commerce-lib-app/config.
Quality Bar
aio app buildcompletes without errors
Chaining
After aio app build passes:
- Add webhook interceptors — invoke
commerce-app-webhooksto intercept Commerce operations before or after they execute - Add event subscriptions — invoke
commerce-app-eventingto subscribe to Commerce or external events - Extend the Admin UI — invoke
commerce-app-admin-uito add custom columns, mass actions, order view buttons, or menu entries in Commerce Admin
References
- assets/business-config.ts — Reference config showing all field types with inline constraint comments
FAQ
What does the commerce-app-business-config skill do?
Manage custom business configuration in an Adobe Commerce app. Use when the user wants to add, modify, or remove merchant-configurable settings (config fields, admin config, store configuration) exposed through Commerce Admin. Creates typed config fields (text, password, email, url, tel, boolean, list) in businessConfig.schema. Requires a base app initialized with commerce-app-init.
How do I install commerce-app-business-config?
Run npx skills add https://github.com/adobe/aio-commerce-sdk --skill commerce-app-business-config in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/commerce-app-business-config/ (personal) or .claude/skills/commerce-app-business-config/ (project).
Which AI agents can use commerce-app-business-config?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is commerce-app-business-config safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains commerce-app-business-config?
It is published by adobe in adobe/aio-commerce-sdk. It has 80 recorded installs.
More from adobe/aio-commerce-sdk
commerce-app-init
adobe/aio-commerce-sdk
Scaffold a new Adobe Commerce app using the aio-commerce-sdk. Creates the base project structure and app.commerce.config file with metadata. Use when the user wants to create a new Commerce app from scratch or initialize a bare Commerce app project. After scaffolding, chains to appbuilder-project-init for Developer Console setup (project, workspace, API subscriptions) when the user wants to deploy. Does not configure extensibility domains — use commerce-app-eventing, commerce-app-webhooks, commerce-app-business-config, commerce-app-admin-ui, or commerce-app-storage for that.
commerce-app-eventing
adobe/aio-commerce-sdk
Add or modify Commerce and external event subscriptions, configure event field extraction and filter rules in an Adobe Commerce app. Use when the user wants to set up event-driven workflows triggered by Commerce operations (such as order placement or catalog changes) or third-party systems. Requires a base app initialized with commerce-app-init.
commerce-app-webhooks
adobe/aio-commerce-sdk
Add or modify webhook interceptors in an Adobe Commerce app. Use when the user wants to intercept Commerce operations to validate input, append data, or modify behavior — before or after execution. Requires a base app initialized with commerce-app-init.
commerce-app-storage
adobe/aio-commerce-sdk
Integrate App Builder Database Storage (@adobe/aio-lib-db) into an Adobe Commerce app and scaffold a runtime action that reads and writes documents. Use when the user wants persistent, queryable storage backing a Commerce app — either from a web action (HTTP-invokable) or from an event/webhook handler. Requires a base app initialized with commerce-app-init.
Popular business & finance skills
sales-enablement
coreyhaines31/marketingskills
When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also use when the user mentions 'sales deck,' 'pitch deck,' 'one-pager,' 'leave-behind,' 'objection handling,' 'deal-specific ROI analysis,' 'demo script,' 'talk track,' 'sales playbook,' 'proposal template,' 'buyer persona card,' 'battle card,' 'battlecard,' 'competitive one-pager,' 'win-loss analysis,' 'why are we losing deals,' 'loss reasons,' 'how do I respond to this objection,' 'prospect just said,' 'help my sales team,' 'sales materials,' or 'what should I give my sales reps,' 'cold call script,' or 'voicemail script.' Use this for any document or asset that helps a sales team close deals. For public competitor comparison pages, see competitors. For running buyer interviews or churn research, see customer-research. For marketing website copy, see copywriting. For cold outreach emails, see cold-email. For the offer being sold (bonuses, guarantees, pricing structure),
revops
coreyhaines31/marketingskills
When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'outbound pipeline stages,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,' 'marketing-to-sales handoff,' 'data hygiene,' 'leads aren't getting to sales,' 'pipeline management,' 'lead qualification,' or 'when should marketing hand off to sales.' Use this for anything involving the systems and processes that connect marketing to revenue. For cold outreach emails, see cold-email. For email drip campaigns, see emails. For pricing decisions, see pricing.
sales-funnel-blueprint
autonnel/autonnel-skills
Turn an offer into a concrete multi-step sales funnel spec - page-by-page structure, price ladder, copy outline and the metrics each step must hit. Use when asked to build a sales funnel, marketing funnel, landing page flow, lead magnet funnel, webinar funnel, tripwire or VSL funnel, when planning a product launch page flow, or when someone asks "what pages do I need" for selling something online.
pricing
coreyhaines31/marketingskills
When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' 'should I offer a free plan,' 'pricing page teardown,' 'pricing page audit,' 'is my pricing page AI-readable,' or 'can AI read my pricing.' Use this whenever someone is figuring out what to charge, how to structure their plans, or wants to audit a pricing page (for humans and for the AI agents that shortlist tools). For in-app upgrade screens, see paywalls. For offer construction (bonuses, guarantees, value framing, naming) on services/courses/coaching/high-ticket B2B, see offers.
cross-border-ecommerce
nexscope-ai/ecommerce-skills
Cross-border e-commerce expansion advisor. Scores target markets on 8 weighted dimensions (market size, ecommerce penetration, competition, regulatory complexity, logistics infrastructure, payment ecosystem, cultural distance, IP protection), compares 5 fulfillment models with cost and transit data, provides country-by-country tax/duty compliance guides (EU VAT/IOSS, UK VAT, US sales tax, CA GST, AU GST, JP consumption tax), maps local payment preferences by market, and builds a phased expansion roadmap. No API key required.
pricing-strategy
coreyhaines31/marketingskills
When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' or 'should I offer a free plan.' Use this whenever someone is figuring out what to charge or how to structure their plans. For in-app upgrade screens, see paywall-upgrade-cro.