Asynchronous web endpoints

An asynchronous web endpoint intercepts messages to a Web API and writes them to the message queue. Each time the system accepts such an API request, it generates a UUID identifier. Adobe Commerce includes this UUID when it adds the message to the queue. Then, a consumer reads the messages from the queue and executes them one-by-one.

Commerce supports the following types of asynchronous requests:

• POST
• PUT
• DELETE
• PATCH

The route to all asynchronous calls contains the prefix /async, added before /V1 of a standard synchronous endpoint. For example:

Copy
POST /async/V1/products
PUT /async/V1/products/:sku
Copied to your clipboard
POST /async/V1/products
PUT /async/V1/products/:sku

The REST API documentation provides a list of all current synchronous Commerce API routes.

The response of an asynchronous request contains the following fields:

Sample usage

The following call asynchronously changes the price of the product that has a sku of 24-MB01:

Copy
PUT <host>/rest/<store_code>/async/V1/products/24-MB01
Copied to your clipboard
PUT <host>/rest/<store_code>/async/V1/products/24-MB01

Payload

Copy
{
  "product": {
    "price": 29
  }
}
Copied to your clipboard
{
  "product": {
    "price": 29
  }
}

Response

Commerce generates a bulk_uuid for each asynchronous request. Use the bulk_uuid to determine the operation status of your request.

Copy
{
    "bulk_uuid": "fbfca270-7a90-4c4e-9f32-d6cf3728cdc7",
    "request_items": [
        {
            "id": 0,
            "data_hash": "9c1bd4bfd8defcc856ddf129cc01d172625d139d5f7dcf53b6cb09a0e9a843a3",
            "status": "accepted"
        }
    ],
    "errors": false
}
Copied to your clipboard
{
    "bulk_uuid": "fbfca270-7a90-4c4e-9f32-d6cf3728cdc7",
    "request_items": [
        {
            "id": 0,
            "data_hash": "9c1bd4bfd8defcc856ddf129cc01d172625d139d5f7dcf53b6cb09a0e9a843a3",
            "status": "accepted"
        }
    ],
    "errors": false
}

Store scopes

You can specify a store code (which is labeled in the Admin as store view code) in the route of an asynchronous endpoint so that it operates on a specific store, as shown below:

Copy
POST /<store_code>/async/V1/products
PUT /<store_code>/async/V1/products/:sku
Copied to your clipboard
POST /<store_code>/async/V1/products
PUT /<store_code>/async/V1/products/:sku

As a result, the asynchronous calls update the products on the specific store, instead of the default store.

You can specify the all store code to perform operations on all existing stores:

Copy
POST /all/async/V1/products
PUT /all/async/V1/products/:sku
Copied to your clipboard
POST /all/async/V1/products
PUT /all/async/V1/products/:sku

Fallback and creating/updating objects when setting store scopes

The following rules apply when you create or update an object, such as a product.

• If you do not set the store code while creating a new product, Commerce creates a new object with all values set globally for each scope.
• If you do not set the store code while updating a product, then by fallback, Commerce updates values for the default store only.
• If you include the all parameter, then Commerce updates values for all store scopes (in case a particular store doesn't yet have its own value set).
• If <store_code> parameter is set, then values for only defined store will be updated.

Last updated 9/8/2023

Was this helpful?

Yes

No