Bulk endpoints

Bulk API endpoints differ from other REST endpoints in that they combine multiple calls of the same type into an array and execute them as a single request. The endpoint handler splits the array into individual entities and writes them as separate messages to the message queue.

Cron jobs are the default mechanism for managing message queues and starting message queue consumers, but you can also use external process control systems (like Supervisor) to monitor process management. You can use the bin/magento queue:consumers:start async.operations.all command to manually start the async.operations.all consumer that handles asynchronous and bulk API messages. However, manually starting consumers is not recommended because it requires you to keep your terminal session connected.

Routes

To call a bulk endpoint, add the prefix /async/bulk before the /V1 of a synchronous endpoint route. For example:

Copy
POST /async/bulk/V1/products
POST /async/bulk/V1/customers
Copied to your clipboard
POST /async/bulk/V1/products
POST /async/bulk/V1/customers

Endpoint routes that contain input parameters require additional changes. For example, PUT /V1/products/:sku/media/:entryId contains the :sku and :entryId input parameters. The route of a bulk request cannot contain input parameters, so you must change the route so that it does not contain any. To do this, replace the colon (:) with by and change the first letter of the parameter to uppercase.

The following table provides several examples:

Payloads

The payload of a bulk request contains an array of request bodies. For example, the minimal payload for creating four customers with POST /async/bulk/V1/customers would be structured as follows:

Copy
[{
    "customer": {
        "email": "mshaw@example.com",
        "firstname": "Melanie Shaw",
        "lastname": "Doe"
    },
    "password": "Strong-Password"
},
{
    "customer": {
        "email": "bmartin@example.com",
        "firstname": "Bryce",
        "lastname": "Martin"
    },
    "password": "Strong-Password"
},
{
    "customer": {
        "email": "bmartin@example.com",
        "firstname": "Bryce",
        "lastname": "Martin"
    },
    "password": "Strong-Password"
},
{
    "customer": {
        "email": "tgomez@example.com",
        "firstname": "Teresa",
        "lastname": "Gomez"
    },
    "password": "Strong-Password"
}
]
Copied to your clipboard
[{
    "customer": {
        "email": "mshaw@example.com",
        "firstname": "Melanie Shaw",
        "lastname": "Doe"
    },
    "password": "Strong-Password"
},
{
    "customer": {
        "email": "bmartin@example.com",
        "firstname": "Bryce",
        "lastname": "Martin"
    },
    "password": "Strong-Password"
},
{
    "customer": {
        "email": "bmartin@example.com",
        "firstname": "Bryce",
        "lastname": "Martin"
    },
    "password": "Strong-Password"
},
{
    "customer": {
        "email": "tgomez@example.com",
        "firstname": "Teresa",
        "lastname": "Gomez"
    },
    "password": "Strong-Password"
}
]

Responses

The response contains an array that indicates whether the call successfully added each request to the message queue. Although the duplicated request to create a customer will fail, Commerce added it to the message queue successfully.

Copy
{
    "bulk_uuid": "799a59c0-09ca-4d60-b432-2953986c1c38",
    "request_items": [
        {
            "id": 0,
            "data_hash": "3d3d853839dd442d0b99a1badea756a03f19ffb0fb7aab672c05f83d5a914181",
            "status": "accepted"
        },
        {
            "id": 1,
            "data_hash": "bf8859d03545f0fa80084a47348a629cdf571fc064b952e7396c338d5cf3bf6e",
            "status": "accepted"
        },
        {
            "id": 2,
            "data_hash": "876f3f2e4b226d54dcbf3f5ce752a9f748a45310261d2dd5cc7a7c9ef74b4369",
            "status": "accepted"
        },
        {
            "id": 3,
            "data_hash": "9c1bd4bfd8defcc856ddf129cc01d172625d139d5f7dcf53b6cb09a0e9a843a3",
            "status": "accepted"
        }
    ],
    "errors": false
}
Copied to your clipboard
{
    "bulk_uuid": "799a59c0-09ca-4d60-b432-2953986c1c38",
    "request_items": [
        {
            "id": 0,
            "data_hash": "3d3d853839dd442d0b99a1badea756a03f19ffb0fb7aab672c05f83d5a914181",
            "status": "accepted"
        },
        {
            "id": 1,
            "data_hash": "bf8859d03545f0fa80084a47348a629cdf571fc064b952e7396c338d5cf3bf6e",
            "status": "accepted"
        },
        {
            "id": 2,
            "data_hash": "876f3f2e4b226d54dcbf3f5ce752a9f748a45310261d2dd5cc7a7c9ef74b4369",
            "status": "accepted"
        },
        {
            "id": 3,
            "data_hash": "9c1bd4bfd8defcc856ddf129cc01d172625d139d5f7dcf53b6cb09a0e9a843a3",
            "status": "accepted"
        }
    ],
    "errors": false
}

DELETE requests

The following call asynchronously deletes CMS blocks with IDs 1 and 2:

Copy
DELETE <host>/rest/async/bulk/V1/cmsPage/byPageId
Copied to your clipboard
DELETE <host>/rest/async/bulk/V1/cmsPage/byPageId

DELETE request payload

Copy
[
    {
        "pageId": "1"
    },
    {
        "pageId": "2"
    }
]
Copied to your clipboard
[
    {
        "pageId": "1"
    },
    {
        "pageId": "2"
    }
]

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/bulk/V1/products
PUT /<store_code>/async/bulk/V1/products/bySku
Copied to your clipboard
POST /<store_code>/async/bulk/V1/products
PUT /<store_code>/async/bulk/V1/products/bySku

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/bulk/V1/products
PUT /all/async/bulk/V1/products/bySku
Copied to your clipboard
POST /all/async/bulk/V1/products
PUT /all/async/bulk/V1/products/bySku

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 7/24/2024

Was this helpful?

Yes

No