REST endpoints for Admin UI SDK

Adobe Commerce provides several REST endpoints that interact with the Admin UI SDK processes. These endpoints require an admin token on PaaS systems or a token using Adobe's Identity Management System (IMS) on SaaS systems.

Mass actions without iFrames

When a mass action displayIframe parameter is set to false, you must account for additional factors.

Application failures:

• Commerce expects application responses to contain the error status and message.
• Commerce logs the error and displays an error banner notification to the user.

Connection interruption failures:

By default, Commerce waits 10 seconds for a response, though the extension point can customize this value. When the timeout is reached, Commerce:

• Logs a 408 timeout status and error message.
• Displays an error banner notification.
• Sends the admin_ui_sdk_mass_action_request_failed event. The application can subscribe to this event to take action, such as rolling back updates in Commerce.

Additional details through REST API:

The GET V1/adminuisdk/massaction/<requestId> endpoint returns details of the failed request when a mass action without an iFrame fails to execute.

Headers:

Responses:

• 200: Successful response with the following response payload:

  {
      "id": Unique internal ID,
      "request_id": Request ID,
      "action_id": Mass Action ID that failed,
      "grid_type": Grid type: product, order or customer,
      "error_status": Error Status,
      "error_message": Error Message,
      "request_timestamp": Timestamp,
      "selected_ids": Array of selected IDs in the grid
  }
  

Example usage:

curl -X GET \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" \
    '<ADOBE_COMMERCE_URL>/rest/V1/adminuisdk/massaction/<REQUEST_ID>'

Recommendations:

• Use bulk update in Commerce to avoid inconsistency issues in case of failures.
• Event and REST API responses contain the list of selected IDs for a request. It is the application's responsibility to monitor updates or failures in Commerce.

Order view button without iFrames

When an order view button displayIframe parameter is set to false, you must account for additional factors.

Application failures:

• Commerce expects application responses to contain the error status and message.
• Commerce logs the error and displays an error banner notification to the user.

Connection interruption failures:

By default, Commerce waits 10 seconds for a response, though the extension point can customize this value. When the timeout is reached, Commerce:

• Logs a 408 timeout status and error message.
• Displays an error banner notification.
• Sends the admin_ui_sdk_order_view_button_request_failed event. The application can subscribe to this event to take action, such as rolling back updates in Commerce.

Additional details through REST API:

The GET V1/adminuisdk/orderviewbutton/<requestId> endpoint returns details of the failed request when an order view button without iFrame fails to execute.

Headers:

Responses:

• 200: Successful response with the following response payload:

  {
      "id": Unique internal ID,
      "request_id": Request ID,
      "button_id": Button ID that failed,
      "order_id": Order ID that failed,
      "error_status": Error Status,
      "error_message": Error Message,
      "request_timestamp": Timestamp
  }
  

Example usage:

curl -X GET \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" \
    '<ADOBE_COMMERCE_URL>/rest/V1/adminuisdk/orderviewbutton/<REQUEST_ID>'

Recommendations

• Event and REST API responses contain the order ID for a request. It is the application's responsibility to monitor updates or failures in Commerce.

Permission Checks

The following endpoint lets an extension point verify whether the currently authenticated admin user is authorized for an Admin UI SDK ACL resource that the extension registered.

Check a user's permission for an ACL resource

POST /V1/adminuisdk/permission/check

Checks whether the currently authenticated admin user holds the specified Admin UI SDK ACL resource. The resource must have been registered by an extension point (for example, through a menu, mass action, or order view button registration) for this endpoint to grant it. Resources that are unregistered or unrecognized return false, the same as a genuine permission denial, so the response cannot be used to determine whether a resource ID exists.

Headers:

Request body:

Example usage:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" \
    -d '{"resource": "Acme_Promotions::manage_promotions"}' \
    '<ADOBE_COMMERCE_URL>/rest/V1/adminuisdk/permission/check'

Responses:

• 200: Successful response with the following response payload:

  {
      "allowed": true
  }
  

  allowed is false both when the resource isn't registered by any extension point and when the user's role doesn't grant it.

• 400: Bad request: resource is missing, empty, or contains only whitespace.

• 401: Unauthorized

• 500: Internal server error

App Management

The following endpoints manage selected extensions stored in the Commerce database.

Save a selected extension

POST /V1/adminuisdk/extension

Saves a selected extension record to the database.

Headers:

Request body:

All fields are defined in the extension object.

data-variant=info

data-slots=text

Example usage:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" \
    -d '{"extension": {"extension_name": "my-extension", "extension_title": "My Extension",  "extension_workspace": "production"}}' \
    '<ADOBE_COMMERCE_URL>/rest/V1/adminuisdk/extension'

Responses:

• 400: Bad request
• 401: Unauthorized
• 500: Internal server error

Delete a selected extension

DELETE /V1/adminuisdk/extension/<workspace_name>/<extension_name>

Deletes the specified extension from the database by workspace name and extension name.

Headers:

Path parameters:

Example usage:

curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" \
    '<ADOBE_COMMERCE_URL>/rest/V1/adminuisdk/extension/<WORKSPACE_NAME>/<EXTENSION_NAME>'

Responses:

• 200: Ok
• 401: Unauthorized
• 404: Not Found: Selected extension does not exist.
• 500: Internal server error

Enable or disable the Admin UI SDK

PUT /V1/adminuisdk/config

This endpoint manages whether the Admin UI SDK is enabled. It is available for Admin UI SDK V2 only.

Headers:

Request body:

Example usage:

curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" \
    -d '{"enableAdminUiSdk": true}' \
    '<ADOBE_COMMERCE_URL>/rest/V1/adminuisdk/config'

Responses:

• 200: Successful response with the following response payload:

  {
      "enabled": true
  }
  

• 400: Bad request: enableAdminUiSdk is missing from the request body or is not a valid boolean value.

• 401: Unauthorized

• 500: Internal server error