---
title: "Reconcile Installation (Install or Upgrade)"
method: POST
path: "/installation"
tags: ["Management"]
---

# Reconcile Installation (Install or Upgrade)

`POST /installation`

Desired-state endpoint. Reconciles the app toward the target configuration: when no installation baseline exists it installs the app, except for `post-app-deploy` invocations, which return `409 not-installed`; when a baseline exists it upgrades from the baseline to the version declared in `metadata.version`. An upgrade must keep the installed `metadata.id`; a different application ID is rejected before planning. The chosen branch is reported in the response `operation` field.

## Headers

- `x-gw-ims-org-id` string, required
- `x-aio-commerce-installation-invocation-source` 'post-app-deploy'

## Request body

- object
  - `appData` AppData, required
    - `consumerOrgId` string, required
    - `orgName` string, required
    - `projectId` string, required
    - `projectName` string, required
    - `projectTitle` string, required
    - `workspaceId` string, required
    - `workspaceName` string, required
    - `workspaceTitle` string, required
  - `commerceBaseUrl` string — Commerce instance base URL. Required for a first-time installation; for an upgrade it is optional and derived from the existing Commerce association.
  - `commerceEnv` 'paas' | 'saas' — Commerce deployment flavor. Required for a first-time installation; for an upgrade it is optional and derived from the existing Commerce association.
  - `ioEventsUrl` string, required
  - `ioEventsEnv` string, required

## Response `200`

Manual-mode upgrade: the upgrade plan was created or reused and returned without starting execution (`metadata.upgradeMode` is `manual`).

- object
  - `message` string, required
  - `operation` 'upgrade', required
  - `plan` object, required — The planned upgrade, spanning every participating domain.

## Other responses

- `202` — The operation was accepted for asynchronous execution: either a first-time installation or an automatic upgrade. The `operation` field indicates which branch ran.
- `400` — The request is invalid or could not be parsed (for example, a first-time installation without a `commerceBaseUrl`).
- `401` — 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` — The access token is valid, but it is not allowed to access the requested organization or operation.
- `409` — The request is not actionable. This covers both non-actionable no-op states and real failures. A `409` carrying a `reason` is a graceful no-op the caller can ignore: `not-installed` (a post-deploy invocation cannot install the app), `not-associated` (the app is not associated with a Commerce instance), or `already-current` (the installed version already matches `metadata.version`). A `409` without a `reason` is a real failure — for example, an installation already running or completed, an attempted change to the installed `metadata.id`, or upgrade planning blocked by configuration `issues`.
- `500` — An unexpected server error occurred.

## Changes

- **2026-08-20** `9fc87bd0e1ce` — 9 breaking, 1 warning, 7 info
  - added `subschema #1, subschema #2` to the response body `oneOf` list for the response status `202`
  - the response's body type/format changed from `object`/`` to ``/`` for status `202`
  - removed the required property `activationId` from the response with the `202` status
  - removed the required property `data` from the response with the `202` status
  - …13 more
- **2026-07-06** `7f3e5f61a43a` — 1 info
  - added the optional property `config` to the response with the `202` status
- **2026-07-01** `d85db665cc4c` — 1 warning
  - removed the request property `appData/adminUiViewUrl`
- **2026-06-26** `1375dc66746f` — 1 info
  - added the new optional request property `appData/adminUiViewUrl`
- **2026-06-12** `59e3a5482a5b` — 1 breaking, 2 info
  - request property `commerceEnv` was restricted to a list of enum values
  - added the new `paas` enum value to the request property `commerceEnv`
  - added the new `saas` enum value to the request property `commerceEnv`

[Change history](https://skmtc.dev/adobe/apis/app-management-api/changes/installation/post.md)

---

[API](https://skmtc.dev/adobe/apis/app-management-api.md) · [All operations](https://skmtc.dev/adobe/apis/app-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/adobe/app-management-api/revisions/4b39b5956be9/schema)