{ "openapi": "3.1.0", "info": { "title": "App Management API", "description": "REST API for managing Adobe Commerce App Builder apps: resolving app configuration, managing configuration values, running the installation, upgrade, and uninstallation lifecycle, and managing the scope tree.", "version": "4.0.0", "contact": {}, "license": { "identifier": "Apache-2.0", "name": "Apache-2.0" }, "x-meta": { "packageVersion": "2.0.0" } }, "servers": [ { "url": "/" } ], "paths": { "/app-config": { "get": { "operationId": "getAppConfig", "summary": "Get Commerce App Configuration", "description": "Returns the Commerce App configuration after resolving and validating it against the schema. When `commerceEnv` is provided, webhooks and events are filtered to that Commerce environment; when omitted, the full, unfiltered configuration is returned.", "parameters": [ { "name": "commerceEnv", "in": "query", "description": "When provided, filters the returned webhooks and events to those applicable to this Commerce environment. When omitted, the full configuration is returned.", "required": false, "schema": { "type": "string", "enum": ["paas", "saas"] } }, { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The resolved and validated Commerce App configuration.", "content": { "application/json": { "schema": { "description": "Current app configuration", "type": "object", "properties": { "metadata": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9-]+$" }, "displayName": { "type": "string", "maxLength": 50, "minLength": 1 }, "description": { "type": "string", "maxLength": 255, "minLength": 1 }, "version": { "type": "string", "minLength": 1, "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$" }, "upgradeMode": { "description": "Controls upgrade execution after a deploy: \"auto\" runs the planned upgrade immediately, while \"manual\" returns the plan without executing it. Defaults to \"auto\".", "type": "string", "enum": ["auto", "manual"] } }, "required": [ "id", "displayName", "description", "version", "upgradeMode" ] }, "businessConfig": { "type": "object", "properties": { "schema": { "type": "array", "items": { "oneOf": [ { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "list" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": ["label", "value"] } }, "selectionMode": { "const": "single" }, "default": { "type": "string", "minLength": 1 } }, "required": [ "name", "type", "options", "selectionMode", "default" ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "list" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": ["label", "value"] } }, "selectionMode": { "const": "multiple" }, "default": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "name", "type", "options", "selectionMode", "default" ] } ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "text" }, "default": { "type": "string" } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "password" }, "default": { "const": "" } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "email" }, "default": { "anyOf": [ { "const": "" }, { "type": "string", "format": "email" } ] } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "url" }, "default": { "anyOf": [ { "const": "" }, { "type": "string", "format": "uri" } ] } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "tel" }, "default": { "anyOf": [ { "const": "" }, { "type": "string", "pattern": "^\\+?[0-9\\s\\-()]+$" } ] } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "boolean" }, "default": { "type": "boolean" } }, "required": ["name", "type", "default"] } ] }, "minItems": 1 } }, "required": [] }, "eventing": { "type": "object", "properties": { "commerce": { "type": "array", "items": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/EventProvider" }, "events": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9 _.:()\\-,@/]+$" }, "description": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[a-zA-Z0-9 _.:()\\-,@/]+$" }, "runtimeActions": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9-]+\\/[a-zA-Z0-9-]+$" } }, "name": { "type": "string", "maxLength": 180, "minLength": 1, "pattern": "^(?:plugin|observer)\\.[a-z_]+(?:\\.[a-z_]+)*$" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceEventField" }, "minItems": 1 }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceEventRule" } }, "destination": { "type": "string", "minLength": 1 }, "hipaa_audit_required": { "type": "boolean" }, "priority": { "type": "boolean" }, "force": { "type": "boolean" } }, "required": [ "label", "description", "runtimeActions", "name", "fields" ] } } }, "required": ["provider", "events"] } }, "external": { "type": "array", "items": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/EventProvider" }, "events": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9 _.:()\\-,@/]+$" }, "description": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[a-zA-Z0-9 _.:()\\-,@/]+$" }, "runtimeActions": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9-]+\\/[a-zA-Z0-9-]+$" } }, "name": { "type": "string", "maxLength": 180, "minLength": 1, "pattern": "^[\\w\\-_.]+$" } }, "required": [ "label", "description", "runtimeActions", "name" ] } } }, "required": ["provider", "events"] } } }, "required": [] }, "adminUi": { "description": "The Admin UI SDK v2 configuration block (served as the `adminUi` property of the app-config response).", "$ref": "#/components/schemas/AdminUiConfiguration" }, "installation": { "type": "object", "properties": { "messages": { "type": "object", "properties": { "preInstallation": { "type": "string", "maxLength": 1000, "minLength": 1 }, "postInstallation": { "type": "string", "maxLength": 1000, "minLength": 1 } }, "required": [] }, "customInstallationSteps": { "type": "array", "items": { "type": "object", "properties": { "script": { "type": "string", "minLength": 1, "pattern": "^(?:\\.{0,2}\\/)*[\\w-/]*[\\w-]+\\.js$" }, "name": { "type": "string", "maxLength": 255, "minLength": 1 }, "description": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": ["script", "name", "description"] } } }, "required": [] }, "webhooks": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/RuntimeActionWebhookConfig" }, { "$ref": "#/components/schemas/ExternalUrlWebhookConfig" } ] }, "minItems": 1 }, "openApiSpecUrl": { "description": "URL of the OpenAPI spec for this deployment, scoped to the active capabilities. Includes a content-addressed cache key as a query parameter.", "type": "string", "format": "uri", "examples": [ "https://123456-projectname-workspacename.adobeioruntime.net/api/v1/web/app-management/app-config/openapi.json?ck=4f6a2b9c" ] } }, "additionalProperties": true, "required": ["metadata", "openApiSpecUrl"] } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["App Metadata"] } }, "/config": { "get": { "operationId": "getConfiguration", "summary": "Get Configuration Values", "description": "Returns the application configuration schema and the stored values for the requested scope.", "parameters": [ { "name": "scopeId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "commerceEnv", "in": "query", "required": false, "schema": { "type": "string", "enum": ["paas", "saas"] } }, { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The configuration schema and the stored configuration values for the requested scope. Password fields are masked in the response.", "content": { "application/json": { "schema": { "description": "Current configuration values for the given scope", "type": "object", "properties": { "schema": { "type": "array", "items": { "oneOf": [ { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "list" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": ["label", "value"] } }, "selectionMode": { "const": "single" }, "default": { "type": "string", "minLength": 1 } }, "required": [ "name", "type", "options", "selectionMode", "default" ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "list" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": ["label", "value"] } }, "selectionMode": { "const": "multiple" }, "default": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "name", "type", "options", "selectionMode", "default" ] } ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "text" }, "default": { "type": "string" } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "password" }, "default": { "const": "" } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "email" }, "default": { "anyOf": [ { "const": "" }, { "type": "string", "format": "email" } ] } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "url" }, "default": { "anyOf": [ { "const": "" }, { "type": "string", "format": "uri" } ] } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "tel" }, "default": { "anyOf": [ { "const": "" }, { "type": "string", "pattern": "^\\+?[0-9\\s\\-()]+$" } ] } }, "required": ["name", "type", "default"] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "description": { "type": "string" }, "env": { "type": "array", "items": { "enum": ["paas", "saas"], "type": "string" }, "minItems": 1 }, "type": { "const": "boolean" }, "default": { "type": "boolean" } }, "required": ["name", "type", "default"] } ] } }, "values": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/ConfigScope" }, "config": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigValue" } } }, "required": ["scope", "config"] } }, "required": ["schema", "values"] } } } }, "400": { "description": "The request is invalid or could not be parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Business Configuration"] }, "patch": { "operationId": "patchConfiguration", "summary": "Patch Configuration Values", "description": "Partially updates configuration values for a scope. Unsets those values that are sent with a null value.", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scopeId": { "type": "string", "minLength": 1 }, "config": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "value": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, { "type": "null" } ] } }, "required": ["name", "value"] } } }, "required": ["scopeId", "config"] } } } }, "responses": { "200": { "description": "The configuration values were successfully updated. Returns the updated configuration with password fields masked.", "headers": { "Cache-Control": { "description": "Prevents clients from caching configuration mutation responses.", "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "description": "Configuration values updated for the given scope", "type": "object", "properties": { "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "scope": { "$ref": "#/components/schemas/ConfigScope" }, "config": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigUpdateEntry" } } }, "required": ["message", "timestamp", "scope", "config"] } } } }, "400": { "description": "The request is invalid or could not be parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Business Configuration"] } }, "/installation": { "get": { "operationId": "getInstallationState", "summary": "Get Installation State", "description": "Returns the status of the latest lifecycle attempt, whatever its operation. With `history=true`, also returns the plans of that attempt, the earlier attempts with their plans, and the plans made since the latest attempt. Without a lifecycle attempt, returns the installation record of an older library version, if any, and ignores `history` and `limit`.", "parameters": [ { "name": "history", "in": "query", "description": "When `true`, the body also carries `plans`, `history` and `pendingPlans`. Plans carry the full target configuration.", "required": false, "schema": { "type": "string", "default": "false", "enum": ["true", "false"] } }, { "name": "limit", "in": "query", "description": "How many earlier attempts `history` lists at most. Applies only with `history=true`. When omitted, `history` lists every earlier attempt.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } }, { "name": "x-aio-commerce-installation-invocation-source", "in": "header", "description": "Identifies the source of the request. When set to `post-app-deploy` and no lifecycle attempt exists, returns `204` instead of an older library version's installation record.", "required": false, "schema": { "type": "string", "enum": ["post-app-deploy"] } } ], "responses": { "200": { "description": "The latest lifecycle attempt, with its history on `history=true`, or the installation record of an older library version.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LifecycleAttemptStatus" }, { "$ref": "#/components/schemas/LifecycleAttemptHistory" }, { "$ref": "#/components/schemas/InProgressWorkflowState" }, { "$ref": "#/components/schemas/SucceededWorkflowState" }, { "$ref": "#/components/schemas/FailedWorkflowState" } ] } } } }, "204": { "description": "No installation workflow state or lifecycle attempt has been stored yet." }, "400": { "description": "The `history` or `limit` query parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Management"] }, "post": { "operationId": "startLifecyclePlan", "summary": "Start a Planned Lifecycle Operation", "description": "Starts the pending plan named by `planId`, whatever its operation (install, upgrade or uninstall). Get the plan from `POST /installation/plan`. The plan is made again from the current state before it starts, and the attempt records how it differs from the reviewed plan in `review`.", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } }, { "name": "x-aio-commerce-installation-invocation-source", "in": "header", "description": "Identifies the source of the request. The generated post-deploy hook sends `post-app-deploy`; when that source is present and the app is not installed, reconciliation returns `409 not-installed` instead of starting a first-time installation.", "required": false, "schema": { "type": "string", "enum": ["post-app-deploy"] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleRequest" } } } }, "responses": { "202": { "description": "The plan started. Poll `GET /installation` for its status.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/LifecycleAttemptStatus" }, { "type": "object", "properties": { "message": { "type": "string" }, "activationId": { "description": "The activation id of the background execution.", "type": "string" } }, "required": ["message", "activationId"] } ] } } } }, "400": { "description": "The request is invalid, for example without a `planId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "409": { "description": "The plan cannot start. `reason` tells why: `in-progress` (another attempt is running; `attempt` carries its status), `stale-plan` (the `planId` is not the pending plan, or the installed state now calls for another operation; plan again), `not-associated`, `unreadable-state`, `baseline-missing` (the stored state names a baseline snapshot that no longer exists), `installed-without-config`, or `already-current`. Without a `reason`, planning is blocked by the `issues`, or the application ID changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "reason": { "type": "string" }, "attempt": { "$ref": "#/components/schemas/LifecycleAttemptStatus" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/PlanningIssue" } } }, "required": ["message"] } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Management"] } }, "/installation/plan": { "post": { "operationId": "planLifecycleOperation", "summary": "Plan a Lifecycle Operation", "description": "Plans the install or upgrade the installed state calls for, or an uninstallation when `operation` is `uninstall`. Stores it as the pending plan and returns it for review, together with its issues as a validation result. Start it with `POST /installation` and its `id` as `planId`.", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleRequest" } } } }, "responses": { "200": { "description": "The plan and its validation result.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "valid": { "type": "boolean" }, "summary": { "type": "object", "properties": { "totalIssues": { "type": "number" }, "errors": { "type": "number" }, "warnings": { "type": "number" } }, "required": ["totalIssues", "errors", "warnings"] }, "result": { "$ref": "#/components/schemas/StepValidationResult" } }, "required": ["valid", "summary", "result"] }, { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/PlanPreview" } }, "required": ["plan"] } ] } } } }, "400": { "description": "The request is invalid or could not be parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "409": { "description": "Nothing was planned. `reason` tells why: `in-progress` (an attempt is running; `attempt` carries its status), `not-associated`, `unreadable-state`, `baseline-missing` (the stored state names a baseline snapshot that no longer exists), `installed-without-config`, or `already-current`. Without a `reason`, planning is blocked by the `issues`, or the application ID changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "reason": { "type": "string" }, "attempt": { "$ref": "#/components/schemas/LifecycleAttemptStatus" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/PlanningIssue" } } }, "required": ["message"] } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Management"] } }, "/scope-tree": { "get": { "operationId": "getScopeTree", "summary": "Get Scope Tree", "description": "Returns the scope tree used by Commerce configuration flows.", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The current scope tree, freshly fetched.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeNode" } } }, "required": ["scopes"] } } } }, "203": { "description": "The scope tree returned from cache or persisted storage.", "headers": { "x-cache": { "description": "Indicates that the returned scope tree came from cache.", "schema": { "const": "hit" } } }, "content": { "application/json": { "schema": { "description": "Cached scope tree", "type": "object", "properties": { "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeNode" } } }, "required": ["scopes"] } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Business Configuration"] }, "put": { "operationId": "setCustomScopeTree", "summary": "Set Custom Scope Tree", "description": "Stores a custom scope tree to override the synchronized Commerce scope tree.", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scopes": { "description": "Custom scopes to store. Each code+level combination must be unique across the entire recursive tree.", "type": "array", "items": { "$ref": "#/components/schemas/CustomScopeInput" } } }, "required": ["scopes"] } } } }, "responses": { "200": { "description": "The stored custom scope tree result.", "headers": { "Cache-Control": { "description": "Prevents clients from caching custom scope tree mutation responses.", "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "message": { "const": "Custom scope tree updated successfully" }, "timestamp": { "type": "string", "format": "date-time" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomScopeOutput" } } }, "required": ["message", "timestamp", "scopes"] } }, "required": ["result"] } } } }, "400": { "description": "The request body is invalid: the scopes array is missing or not an array, a scope is missing a required field or has an invalid type, a scope uses a reserved code (commerce or global), or two scopes share the same code and level.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Business Configuration"] } }, "/scope-tree/commerce": { "post": { "operationId": "syncCommerceScopes", "summary": "Sync Commerce Scopes", "description": "Synchronizes scope data from Adobe Commerce and updates the local scope tree.", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "commerceBaseUrl": { "type": "string", "minLength": 1 }, "commerceEnv": { "type": "string", "enum": ["paas", "saas"] } }, "required": ["commerceBaseUrl"] } } } }, "responses": { "200": { "description": "The synchronized Commerce scope tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeNode" } }, "synced": { "const": true } }, "required": ["scopes", "synced"] } } } }, "203": { "description": "The cached scope tree returned when Commerce scopes could not be freshly fetched.", "headers": { "x-cache": { "description": "Indicates that the returned scope tree came from cache.", "schema": { "const": "hit" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeNode" } }, "synced": { "const": false } }, "required": ["scopes", "synced"] } } } }, "400": { "description": "The request is invalid or could not be parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Business Configuration"] }, "delete": { "operationId": "unsyncCommerceScopes", "summary": "Unsync Commerce Scopes", "description": "Removes the synchronized Commerce scope tree and returns the unsync result (or a no-op message if no scopes were stored).", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The result of removing synchronized Commerce scope data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "enum": [ "Commerce scopes unsynced successfully", "No commerce scopes to unsync" ] } }, "required": ["message"] } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Business Configuration"] } }, "/association": { "post": { "operationId": "setAssociation", "summary": "Store Commerce Association", "description": "Persists the Commerce instance the app is associated with so runtime actions can later retrieve it via the SDK helpers.", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "commerceBaseUrl": { "description": "Commerce API base URL of the associated instance.", "type": "string", "format": "uri" }, "commerceEnv": { "description": "Deployment type of the associated Commerce instance.", "type": "string", "enum": ["saas", "paas"] } }, "required": ["commerceBaseUrl", "commerceEnv"] } } } }, "responses": { "200": { "description": "Association data stored successfully. Returns the app's IMS client ID so the Commerce App Management Service can bind record ownership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "description": "The app's IMS S2S client ID.", "type": "string" } }, "required": ["clientId"] } } } }, "400": { "description": "Bad request, the request body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "Internal server error while storing the association data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Association"] }, "delete": { "operationId": "clearAssociation", "summary": "Clear Commerce Association", "description": "Removes the stored Commerce instance details. Called when the app is unassociated.", "parameters": [ { "name": "x-gw-ims-org-id", "in": "header", "description": "Adobe IMS organization ID that identifies the organization for the request.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Association data cleared successfully." }, "401": { "description": "You are not authorized to access this resource. Ensure the IMS token and the x-gw-ims-org-id header are correctly set and valid." }, "403": { "description": "The access token is valid, but it is not allowed to access the requested organization or operation." }, "500": { "description": "Internal server error while clearing the association data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": ["Association"] } } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "error": { "type": "string" } }, "required": ["message"] }, "ValidationErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["message"] }, "AppData": { "type": "object", "properties": { "consumerOrgId": { "type": "string", "minLength": 1 }, "orgName": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "projectName": { "type": "string", "minLength": 1 }, "projectTitle": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "workspaceName": { "type": "string", "minLength": 1 }, "workspaceTitle": { "type": "string", "minLength": 1 } }, "required": [ "consumerOrgId", "orgName", "projectId", "projectName", "projectTitle", "workspaceId", "workspaceName", "workspaceTitle" ] }, "ConfigScope": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "level": { "type": "string" } }, "required": ["id", "code", "level"] }, "ConfigOrigin": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" } }, "required": ["code", "level"] }, "ConfigValue": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "origin": { "$ref": "#/components/schemas/ConfigOrigin" } }, "required": ["name", "value", "origin"] }, "ConfigUpdateEntry": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": ["name", "value"] }, "StepMetaInfo": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" } }, "required": ["label"] }, "ValidationIssue": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "enum": ["error", "warning", "info"] }, "details": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } } }, "required": ["code", "message", "severity"] }, "EventProvider": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9 _.:()\\-,@/]+$" }, "description": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[a-zA-Z0-9 _.:()\\-,@/]+$" }, "key": { "type": "string", "maxLength": 50, "pattern": "^[a-zA-Z0-9-]+$" } }, "required": ["label", "description"] }, "CommerceEventField": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "^([a-zA-Z0-9_\\-.[\\]]+|\\*)$" }, "source": { "type": "string" } }, "required": ["name"] }, "CommerceEventRule": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "enum": [ "greaterThan", "lessThan", "equal", "regex", "in", "onChange" ] }, "value": { "type": "string", "minLength": 1 } }, "required": ["field", "operator", "value"] }, "WebhookField": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "source": { "type": "string" } }, "required": ["name"] }, "WebhookRule": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": ["field", "operator", "value"] }, "WebhookHeader": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": ["name", "value"] }, "WebhookDefinition": { "type": "object", "properties": { "webhook_method": { "type": "string", "minLength": 1 }, "webhook_type": { "type": "string", "enum": ["before", "after"] }, "batch_name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_]+$" }, "batch_order": { "type": "number", "minimum": 0 }, "hook_name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_]+$" }, "priority": { "type": "number", "minimum": 0 }, "required": { "type": "boolean" }, "soft_timeout": { "type": "number", "minimum": 0 }, "timeout": { "type": "number", "minimum": 0 }, "method": { "type": "string", "enum": ["POST", "PUT", "DELETE", "GET"] }, "fallback_error_message": { "type": "string" }, "ttl": { "type": "number", "minimum": 0 }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookField" } }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookRule" } }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookHeader" } } }, "required": [ "webhook_method", "webhook_type", "batch_name", "hook_name", "method" ] }, "RuntimeActionWebhookConfig": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": ["validation", "append", "modification"] }, "runtimeAction": { "type": "string", "minLength": 1 }, "requireAdobeAuth": { "type": "boolean" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookDefinition" }, { "not": { "properties": { "url": {} }, "required": ["url"] } } ] } }, "required": ["label", "description", "runtimeAction", "webhook"] }, "ExternalUrlWebhookConfig": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": ["validation", "append", "modification"] }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookDefinition" }, { "properties": { "url": { "type": "string", "format": "uri" } }, "required": ["url"] } ] } }, "not": { "properties": { "runtimeAction": {} }, "required": ["runtimeAction"] }, "required": ["label", "description", "webhook"] }, "StepStatus": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/StepMetaInfo" }, "status": { "enum": ["pending", "in-progress", "succeeded", "failed"] }, "startedAt": { "description": "When the step started executing.", "type": "string", "format": "date-time" }, "completedAt": { "description": "When the step succeeded or failed.", "type": "string", "format": "date-time" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/StepStatus" } } }, "required": ["name", "id", "path", "meta", "status", "children"], "title": "StepStatus" }, "StepValidationResult": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/StepMetaInfo" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/StepValidationResult" } } }, "required": ["name", "path", "meta", "issues", "children"], "title": "StepValidationResult" }, "ScopeNode": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "label": { "type": "string" }, "level": { "type": "string" }, "is_editable": { "type": "boolean" }, "is_final": { "type": "boolean" }, "is_removable": { "type": "boolean" }, "commerce_id": { "type": "number" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeNode" } } }, "required": [ "id", "code", "label", "level", "is_editable", "is_final", "is_removable" ], "title": "ScopeNode" }, "CustomScopeOutput": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "label": { "type": "string" }, "level": { "type": "string" }, "is_editable": { "type": "boolean" }, "is_final": { "type": "boolean" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/CustomScopeOutput" } } }, "required": ["id", "code", "label", "level", "is_editable", "is_final"], "title": "CustomScopeOutput" }, "AdminUiMenu": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_/:]+$" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "pageTitle": { "type": "string", "minLength": 1 }, "parentMenu": { "type": "string", "enum": [ "sales", "catalog", "customers", "marketing", "content", "reports", "stores", "system" ] }, "sandboxPermissions": { "$ref": "#/components/schemas/AdminUiSandboxPermissions" } }, "required": ["id", "label", "description"] }, "AdminUiMassAction": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "type": { "const": "view" }, "path": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "confirm": { "$ref": "#/components/schemas/AdminUiConfirm" }, "notifications": { "$ref": "#/components/schemas/AdminUiNotifications" }, "selectionLimit": { "type": "number", "minimum": 1 }, "sandboxPermissions": { "$ref": "#/components/schemas/AdminUiSandboxPermissions" } }, "required": ["id", "label", "type", "path"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "type": { "const": "worker" }, "runtimeAction": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "confirm": { "$ref": "#/components/schemas/AdminUiConfirm" }, "notifications": { "$ref": "#/components/schemas/AdminUiNotifications" }, "selectionLimit": { "type": "number", "minimum": 1 }, "timeout": { "type": "number", "minimum": 1 } }, "required": ["id", "label", "type", "runtimeAction"], "additionalProperties": false } ] }, "AdminUiConfiguration": { "type": "object", "properties": { "menu": { "$ref": "#/components/schemas/AdminUiMenu" }, "order": { "type": "object", "properties": { "massActions": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUiMassAction" } }, "gridColumns": { "$ref": "#/components/schemas/AdminUiGridColumns" }, "viewButtons": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUiOrderViewButton" } } } }, "product": { "type": "object", "properties": { "massActions": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUiMassAction" } }, "gridColumns": { "$ref": "#/components/schemas/AdminUiGridColumns" } } }, "customer": { "type": "object", "properties": { "massActions": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUiMassAction" } }, "gridColumns": { "$ref": "#/components/schemas/AdminUiGridColumns" } } }, "invoice": { "type": "object", "properties": { "gridColumns": { "$ref": "#/components/schemas/AdminUiGridColumns" } } }, "creditMemo": { "type": "object", "properties": { "gridColumns": { "$ref": "#/components/schemas/AdminUiGridColumns" } } }, "shipment": { "type": "object", "properties": { "gridColumns": { "$ref": "#/components/schemas/AdminUiGridColumns" } } }, "newsletter": { "type": "object", "properties": { "massActions": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUiMassAction" } }, "gridColumns": { "$ref": "#/components/schemas/AdminUiGridColumns" } } } }, "additionalProperties": false, "required": [] }, "AdminUiGridColumns": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "runtimeAction": { "type": "string", "minLength": 1 }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "boolean", "date", "datetime", "float", "integer", "string" ] }, "align": { "type": "string", "enum": ["left", "right", "center"] } }, "required": ["id", "label", "type", "align"] }, "minItems": 1 } }, "required": ["label", "description", "runtimeAction", "columns"] }, "AdminUiOrderViewButton": { "discriminator": { "propertyName": "type", "mapping": { "view": "#/components/schemas/AdminUiOrderViewNavigationButton", "worker": "#/components/schemas/AdminUiOrderViewWorkerButton" } }, "oneOf": [ { "$ref": "#/components/schemas/AdminUiOrderViewNavigationButton" }, { "$ref": "#/components/schemas/AdminUiOrderViewWorkerButton" } ] }, "AdminUiConfirm": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "AdminUiNotifications": { "type": "object", "properties": { "success": { "type": "string", "minLength": 1 }, "error": { "type": "string", "minLength": 1 } } }, "AdminUiSandboxPermissions": { "type": "array", "items": { "type": "string", "enum": ["allow-downloads", "allow-modals", "allow-popups"] }, "minItems": 1 }, "CustomScopeInput": { "type": "object", "properties": { "id": { "type": "string", "pattern": ".*\\S.*" }, "code": { "type": "string", "pattern": "^(?!\\s*(?:commerce|global)\\s*$).*\\S.*$" }, "label": { "type": "string", "pattern": ".*\\S.*" }, "level": { "type": "string", "default": "base", "pattern": ".*\\S.*" }, "is_editable": { "type": "boolean" }, "is_final": { "type": "boolean" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/CustomScopeInput" } } }, "required": ["code", "label", "is_editable", "is_final"], "title": "CustomScopeInput" }, "InProgressWorkflowState": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "const": "in-progress" }, "startedAt": { "type": "string", "format": "date-time" }, "step": { "$ref": "#/components/schemas/StepStatus" }, "config": { "description": "The validated app configuration recorded at install time. Present so uninstallation can be sourced from what was actually installed rather than the current request config. Absent on states persisted before this field was introduced.", "type": "object", "additionalProperties": true }, "data": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "not": { "properties": { "operation": {} }, "required": ["operation"] }, "required": ["id", "status", "startedAt", "step", "data"] }, "SucceededWorkflowState": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "const": "succeeded" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "step": { "$ref": "#/components/schemas/StepStatus" }, "config": { "description": "The validated app configuration recorded at install time. Present so uninstallation can be sourced from what was actually installed rather than the current request config. Absent on states persisted before this field was introduced.", "type": "object", "additionalProperties": true }, "data": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "metadata": { "type": "object", "properties": { "isRetry": { "type": "boolean" } }, "required": ["isRetry"] } }, "not": { "properties": { "operation": {} }, "required": ["operation"] }, "required": ["id", "status", "startedAt", "completedAt", "step", "data"] }, "FailedWorkflowState": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "const": "failed" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "step": { "$ref": "#/components/schemas/StepStatus" }, "config": { "description": "The validated app configuration recorded at install time. Present so uninstallation can be sourced from what was actually installed rather than the current request config. Absent on states persisted before this field was introduced.", "type": "object", "additionalProperties": true }, "data": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "error": { "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" } }, "key": { "type": "string" }, "message": { "type": "string" }, "payload": {} }, "required": ["path", "key"] }, "metadata": { "type": "object", "properties": { "isRetry": { "type": "boolean" } }, "required": ["isRetry"] } }, "not": { "properties": { "operation": {} }, "required": ["operation"] }, "required": [ "id", "status", "startedAt", "completedAt", "step", "data", "error" ] }, "AdminUiOrderViewNavigationButton": { "type": "object", "properties": { "type": { "type": "string", "const": "view" }, "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "path": { "type": "string", "minLength": 1 }, "level": { "type": "number", "enum": [-1, 0, 1] }, "sortOrder": { "type": "number", "minimum": 1 }, "confirm": { "$ref": "#/components/schemas/AdminUiConfirm" }, "sandboxPermissions": { "$ref": "#/components/schemas/AdminUiSandboxPermissions" }, "notifications": { "$ref": "#/components/schemas/AdminUiNotifications" } }, "required": ["type", "id", "label", "path"] }, "AdminUiOrderViewWorkerButton": { "type": "object", "properties": { "type": { "type": "string", "const": "worker" }, "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "runtimeAction": { "type": "string", "minLength": 1 }, "level": { "type": "number", "enum": [-1, 0, 1] }, "sortOrder": { "type": "number", "minimum": 1 }, "confirm": { "$ref": "#/components/schemas/AdminUiConfirm" }, "timeout": { "type": "number", "minimum": 1 }, "notifications": { "$ref": "#/components/schemas/AdminUiNotifications" } }, "required": ["type", "id", "label", "runtimeAction"] }, "LifecycleRequest": { "type": "object", "properties": { "appData": { "$ref": "#/components/schemas/AppData" }, "ioEventsUrl": { "type": "string" }, "ioEventsEnv": { "type": "string" }, "operation": { "description": "Set to `uninstall` to plan an uninstallation. Without it, `POST /installation/plan` plans the install or upgrade the installed state calls for.", "const": "uninstall" }, "planId": { "description": "The id of the pending plan to start. Required by `POST /installation`.", "type": "string" } }, "required": ["appData", "ioEventsUrl", "ioEventsEnv"] }, "LifecycleAttemptStatus": { "description": "The status of a lifecycle attempt. Only one lifecycle operation runs at a time; `id` identifies the run.", "type": "object", "properties": { "id": { "type": "string" }, "previousAttemptId": { "description": "The attempt this one replaced as the latest, or `null` for the first attempt.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "planId": { "description": "The plan the attempt executed.", "type": "string" }, "previousPlanId": { "description": "The pending plan the executed plan replaced, or `null` when none was pending.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "activations": { "description": "The OpenWhisk activations that worked on the attempt. Read their logs with `aio rt activation logs `.", "type": "object", "properties": { "start": { "description": "The activation that started the attempt.", "type": "string" }, "execution": { "description": "The activation that executed the attempt. Absent until execution begins.", "type": "string" } }, "required": ["start"] }, "operation": { "type": "string", "enum": ["install", "upgrade", "uninstall"] }, "status": { "type": "string", "enum": ["pending", "in-progress", "succeeded", "failed"] }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "description": "Present once the attempt succeeded or failed.", "type": "string", "format": "date-time" }, "result": { "description": "Present when the attempt succeeded. What the attempt left installed, or `null` when it left nothing installed.", "anyOf": [ { "type": "object", "properties": { "snapshotId": { "description": "The snapshot captured after the attempt.", "type": "string" }, "appVersion": { "description": "The app version the attempt installed.", "type": "string" } }, "required": ["snapshotId", "appVersion"] }, { "type": "null" } ] }, "step": { "$ref": "#/components/schemas/StepStatus" }, "data": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "error": { "description": "Present when the attempt failed.", "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" } }, "key": { "type": "string" }, "message": { "type": "string" }, "payload": {} }, "required": ["path", "key"] }, "review": { "description": "How the started plan differs from the reviewed one. Present when the attempt started from a reviewed plan.", "type": "object", "additionalProperties": true } }, "required": [ "id", "previousAttemptId", "planId", "previousPlanId", "activations", "operation", "status", "startedAt", "step", "data" ] }, "LifecycleAttemptHistory": { "description": "The status of the latest lifecycle attempt with the trail that led to it.", "allOf": [ { "$ref": "#/components/schemas/LifecycleAttemptStatus" }, { "type": "object", "properties": { "plans": { "description": "The plan the attempt executed, followed by the stored plans it replaced, newest first.", "type": "array", "items": { "$ref": "#/components/schemas/LifecyclePlan" } }, "history": { "description": "Earlier attempts, newest first, each with its own plans. Stops at `limit` attempts or at the first attempt that is no longer stored.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/LifecycleAttemptStatus" }, { "type": "object", "properties": { "plans": { "description": "The plan the attempt executed, followed by the stored plans it replaced, newest first.", "type": "array", "items": { "$ref": "#/components/schemas/LifecyclePlan" } } }, "required": ["plans"] } ] } }, "pendingPlans": { "description": "The pending plan followed by the plans it replaced, newest first. Empty when no plan is pending.", "type": "array", "items": { "$ref": "#/components/schemas/LifecyclePlan" } } }, "required": ["plans", "history", "pendingPlans"] } ] }, "LifecyclePlan": { "description": "A lifecycle plan as stored, with the full target configuration.", "type": "object", "properties": { "id": { "type": "string" }, "previousPlanId": { "description": "The pending plan this plan replaced, or `null` when none was pending.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operation": { "type": "string", "enum": ["install", "upgrade", "uninstall"] }, "actionVersion": { "description": "Version of the action that made the plan.", "type": "string" }, "source": { "description": "The state the plan starts from, or `null` when nothing is installed.", "anyOf": [ { "type": "object", "properties": { "snapshotId": { "type": "string" }, "appVersion": { "type": "string" } }, "required": ["snapshotId", "appVersion"] }, { "type": "null" } ] }, "target": { "description": "The state the plan leads to, or `null` when the app ends up with nothing installed.", "anyOf": [ { "type": "object", "properties": { "appVersion": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } }, "required": ["appVersion", "config"] }, { "type": "null" } ] }, "domains": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" } }, "operations": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["path", "operations"] } }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/PlanningIssue" } } }, "required": [ "id", "previousPlanId", "operation", "actionVersion", "source", "target", "domains", "issues" ] }, "PlanningIssue": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } }, "severity": { "type": "string", "enum": ["error", "warning", "info"] }, "blocking": { "description": "Whether the issue prevents the plan from running.", "type": "boolean" } }, "required": ["code", "message", "domain", "severity", "blocking"] }, "PlanPreview": { "description": "A lifecycle plan for review, without internal or sensitive values.", "type": "object", "properties": { "id": { "description": "The `planId` to start the plan with.", "type": "string" }, "operation": { "type": "string", "enum": ["install", "upgrade", "uninstall"] }, "domains": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" } }, "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": ["add", "update", "remove"] }, "label": { "type": "string" }, "reason": { "description": "`change` when the config changed, `drift` when the live state differs from what was installed.", "type": "string", "enum": ["change", "drift"] } }, "required": ["id", "kind", "label", "reason"] } } }, "required": ["path", "operations"] } }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/PlanningIssue" } } }, "required": ["id", "operation", "domains", "issues"] } }, "securitySchemes": { "imsOAuth": { "type": "oauth2", "description": "Adobe IMS OAuth 2.0 access token. Send it as Authorization: Bearer .", "flows": { "clientCredentials": { "scopes": { "AdobeID": "Identifies the user with their Adobe ID", "openid": "Authenticates the user via OpenID Connect" }, "tokenUrl": "https://ims-na1.adobelogin.com/ims/token/v3" } } } } }, "tags": [ { "name": "App Metadata", "description": "Resolve and inspect the Commerce App configuration.", "externalDocs": { "description": "Documentation", "url": "https://developer.adobe.com/commerce/extensibility/app-management/define-app" } }, { "name": "Business Configuration", "description": "Manage app configuration values and the Commerce scope tree.", "externalDocs": { "description": "Documentation", "url": "https://developer.adobe.com/commerce/extensibility/app-management/configuration-schema" } }, { "name": "Management", "description": "Installation, upgrade, and uninstallation lifecycle.", "externalDocs": { "description": "Documentation", "url": "https://developer.adobe.com/commerce/extensibility/app-management/installation/" } } ], "security": [ { "imsOAuth": ["AdobeID", "openid"] } ] }