Sandbox health

src/pages/config.md

@@ -133,6 +133,9 @@
             - [View memberships](sandbox/sandbox-portal/transfer-memberships/list-memberships.md)
             - [Migrate HVD customers to VIP Marketplace](sandbox/sandbox-portal/migrate-hvd-customers/migrate-hvd-customers.md)
             - [View renewal status of memberships](sandbox/sandbox-portal/transfer-memberships/view-renewal-status.md)
+        - [Monitor Sandbox health](sandbox/sandbox-portal/monitor-sandbox-health/index.md)
+          - [Health check API](sandbox/sandbox-portal/monitor-sandbox-health/health-check.md)
+          - [Banners](sandbox/sandbox-portal/monitor-sandbox-health/banner.md)
         - [Portal resources](sandbox/sandbox-portal/portal-resources/index.md)
         - [Other API tools](sandbox/sandbox-portal/other-apis/index.md)
         - [Error codes](sandbox/error-codes.md)

src/pages/docs/release-notes/index.md

@@ -548,6 +548,32 @@ Read more about [Mid-term upgrades](../mid-term/index.md).
 
 ## Sandbox changes
 
+### August 25, 2026
+
+#### Sandbox health check API and portal status banners
+
+Partners can verify Sandbox availability before running integration tests using a new health check API, and can see planned maintenance, known issues, and partial service disruptions communicated directly in the Sandbox Portal through a new status banner.
+
+**What's included**
+
+- **Health check API:** Query `GET /v1/health` to confirm whether VIP Marketplace Sandbox and its underlying business components, customer management, order management, subscription management, and the Sandbox Partner Portal backend, are healthy before sending customer, order, or subscription requests. See [Health check API](../../sandbox/sandbox-portal/monitor-sandbox-health/health-check.md).
+- **Automatic Service Unavailable message:** The Sandbox Portal now performs a health check when it loads and displays a full-page Service Unavailable message if the backend is unreachable, instead of loading partial or inconsistent content.
+- **Sandbox maintenance and outage banner:** Administrators can publish a banner at the top of the Sandbox Portal to communicate planned maintenance windows, known issues, or partial service disruptions, using **Info**, **Warning**, or **Critical** severity levels.
+
+**Why it matters**
+
+Partners can confirm Sandbox availability before running batch integration tests or automate monitoring and alerting on repeated 503 responses, rather than discovering an outage mid-test. The Portal banner also gives partners visibility into ongoing maintenance or known issues without needing to check a separate status page.
+
+**Action required**
+
+| Action | Details |
+|---|---|
+| Call `/v1/health` before bulk operations | Poll the endpoint before sending a batch of customer, order, or subscription requests, not before every individual call. |
+| Respect the minimum poll interval | Use a minimum polling interval of 30 to 60 seconds. Avoid repeated calls during a service disruption. |
+| Handle component-level `DOWN` states | Pause requests to the affected business area (customer, order, or subscription management) until it reports `UP` again. |
+
+For more information, see [Monitor Sandbox health](../../sandbox/sandbox-portal/monitor-sandbox-health/index.md), [Health check API](../../sandbox/sandbox-portal/monitor-sandbox-health/health-check.md), and [Banners](../../sandbox/sandbox-portal/monitor-sandbox-health/banner.md).
+
 ### July 27, 2026
 
 Support for closed discounts in the Sandbox portal:

src/pages/sandbox/sandbox-portal/index.md

@@ -8,3 +8,4 @@ You can use the Sandbox Portal for the following functions:
 - [Order Management](order-management/index.md)
 - [Subscription Management](subscription-management/index.md)
 - [Transfer of memberships](transfer-memberships/index.md)
+- [Monitor Sandbox health](monitor-sandbox-health/index.md)

src/pages/sandbox/sandbox-portal/monitor-sandbox-health/banner.md

@@ -0,0 +1,66 @@
+# Banners
+
+The Sandbox Portal can display two types of messages related to service availability:
+
+- An automatic **Service Unavailable** message that appears when the Portal backend is unavailable.
+- A Sandbox maintenance and outage banner used to communicate planned maintenance, known issues, and partial service disruptions.
+
+## Automatic Service Unavailable banner
+
+When the Sandbox Portal loads, it performs a health check against its backend. If the health check fails, the Portal displays a full-page **Service Unavailable** message instead of loading partially available or potentially inconsistent content.
+
+![Service Unavailable banner in the Sandbox Portal](../image/service_unavailable_banner.png)
+
+This message is generated automatically and is not published by an administrator. It indicates that the Sandbox backend is currently unreachable and does not correspond to a specific maintenance activity or outage notification.
+
+When this message appears:
+
+- The Portal displays a single **Service Unavailable** message instead of loading incomplete or broken content.
+- The issue is with the Sandbox backend and does not indicate a problem with your account or data.
+- You can still sign out from the page.
+- The health check runs only when the page loads and is not retried automatically. To check whether the service has recovered, reload the page.
+
+**Note:** The Service Unavailable message does not distinguish between a Sandbox backend outage and a network connectivity issue on your side. Both conditions result in the same message being displayed.
+
+For information about the health check used to determine Portal availability, see [Health check API](health-check.md).
+
+## Sandbox maintenance and outage banner
+
+The Sandbox Portal includes a banner that communicates planned maintenance windows, known issues, and service disruptions. Unlike the automatic Service Unavailable message, which appears only when the Sandbox Portal backend is unavailable, this banner can be used to communicate partial outages or planned maintenance while the Portal remains accessible.
+
+For example, an administrator might use the banner to notify users that a specific workflow is unavailable or that maintenance is scheduled during a particular time window.
+
+### What you see
+
+The banner appears at the top of the Sandbox Portal on every page. It includes a severity indicator and a message describing the issue or maintenance activity.
+
+Examples:
+
+![alt text](image.png)
+
+![alt text](<Screenshot 2026-08-28 153258.png>)
+
+The banner uses one of the following severity levels:
+
+
+| Severity     | Meaning                                                                                                                    |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| **Info**     | General information or advance notice. No functionality is impacted.                                                       |
+| **Warning**  | A minor issue affects a limited feature or workflow. Core Portal functionality remains available.                          |
+| **Critical** | A significant issue affects one or more key workflows. Users should expect service disruption until the issue is resolved. |
+
+### Banner behaviour
+
+The banner:
+
+- Appears at the top of the Sandbox Portal for all users, regardless of role or distributor.
+- Automatically disappears when the issue is resolved or the maintenance window expires.
+- Supports only one active banner at a time. Publishing a new banner immediately replaces the current banner.
+
+### Important limitations
+
+Keep the following limitations in mind:
+
+- The banner is not targeted. All users see the same message, even if the issue affects only specific users or workflows.
+- Banner updates are not delivered in real time. The Portal checks for an active banner when the page loads, so you may need to refresh the page or navigate within the Portal to see a newly published banner or the removal of an existing one.
+- Banner history is not retained. Only the currently active banner is visible.

src/pages/sandbox/sandbox-portal/monitor-sandbox-health/health-check.md

@@ -0,0 +1,84 @@
+# Health check API
+
+The CPAPI Health Check API enables you to determine whether Adobe Commerce Partner API (CPAPI) is available to serve requests before you send them. Instead of waiting for a customer transaction to fail, you can call this endpoint to verify whether the service, or a specific business component, is currently operational.
+
+The health check reports status by the following business components, rather than individual backend services:
+
+- Customer management
+- Order management
+- Subscription management
+- Sandbox Partner Portal backend
+
+For details about each component, see [Business components](#business-components).
+
+## What it's for
+
+Use the Health Check API for the following scenarios:
+
+- Performing a pre-flight validation before submitting a batch of customer, order, or subscription requests.
+- Determining whether to display a "service temporarily unavailable" message to end customers instead of allowing an operation to fail during processing.
+- Supporting automated monitoring and alerting workflows. Integrate the endpoint into your dashboards or configure alerts when repeated 503 Service Unavailable responses occur.
+
+## What it's not
+
+The Health Check API is not intended for the following purposes:
+
+- Diagnosing or troubleshooting service issues. The API indicates which business component is unavailable, but it does not provide details about the underlying cause.
+- Replacing standard error handling in your application. A healthy status indicates that the service is currently available, but it does not guarantee that all subsequent API requests will succeed.
+
+The API deliberately exposes only a small set of business-oriented components. This abstraction allows Adobe to change underlying infrastructure and implementation details without affecting the API contract.
+
+Regardless of backend changes, the Health Check API always reports the same four business components and one of two possible states: `UP` or `DOWN`.
+
+## Endpoint
+
+```
+GET /v1/health
+```
+
+Sandbox: `https://partnersandbox-stage.adobe.io/v1/health?api_key=<your API key>`
+
+## Authentication
+
+The endpoint uses API key authentication through Adobe I/O Gateway. Use the same API key that you use for other Sandbox CPAPI endpoints when calling this endpoint.
+
+## Response codes
+
+| HTTP status | Meaning |
+|---|---|
+| 200 | All business components are healthy (UP). You can proceed with API requests. |
+| 503 | At least one business component is unhealthy (DOWN). Requests to the affected component may fail until service is restored. |
+
+## Response body
+
+```json
+{
+  "status": "UP",
+  "components": {
+    "customerManagement": "UP",
+    "orderManagement": "UP",
+    "subscriptionManagement": "UP",
+    "sandboxPortal": "UP"
+  }
+}
+```
+
+`status` represents the overall health of CPAPI. `components` provides a health status for each business component, allowing you to identify the affected area without exposing underlying service dependencies.
+
+## Business components
+
+| Component | Covers | If `DOWN`, recommended action |
+|---|---|---|
+| `customerManagement` | Customer and account management capabilities | Account creation and lookup operations are unavailable. Pause customer signup and account calls. |
+| `orderManagement` | Order creation and order processing capabilities, including transfer orders  | Order placement and processing are unavailable. Pause order submission and queue retries. |
+| `subscriptionManagement` | Subscription and entitlement capabilities | Subscription and entitlement changes are unavailable. Pause renewal, upgrade, and downgrade calls. |
+| `sandboxPortal` | Availability of the Sandbox Partner Portal backend | The sandbox portal is unavailable. Sandbox testing may be impacted; there is no production impact. |
+
+A component reports `DOWN` when one or more of its underlying dependencies are unavailable.
+
+**Note:** `customerManagement`, `orderManagement`, and `subscriptionManagement` share common underlying dependencies, such as authentication and the core CPAPI datastore. As a result, an outage in a shared dependency may cause multiple components to report `DOWN` simultaneously.
+
+## Recommended client behavior
+
+- Call `/v1/health` before bulk operations rather than before every individual API request.
+- Use a minimum polling interval, such as 30 to 60 seconds. Avoid repeatedly calling the endpoint during a service disruption.

src/pages/sandbox/sandbox-portal/monitor-sandbox-health/index.md

@@ -0,0 +1,6 @@
+# Monitor Sandbox health
+
+Sandbox can occasionally experience partial outages, dependent service issues, or planned maintenance windows. Use the following resources to verify Sandbox availability before running integration tests and to understand the maintenance and outage messages displayed in the Sandbox Portal.
+
+- [Health check API](health-check.md): Query CPAPI programmatically to confirm that Sandbox and its underlying business components are healthy before running your tests.
+- [Banners](banner.md): Learn about the service availability messages displayed in the Sandbox Portal, including the **Service Unavailable** message shown when the Portal backend services are unavailable, and the **Sandbox maintenance and outage banner** used to communicate planned maintenance, known issues, and partial service disruptions.