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.

Use the bin/magento queue:consumers:start async.operations.all command to start the consumer that handles asynchronous and bulk API messages. Also, before using the Bulk API to process messages, you must install and configure RabbitMQ, which is the default message broker. See RabbitMQ.

Routes

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

1
2
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:

GET and DELETE requests are not supported.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
[{
    "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"
}
]

The second and third requests are duplicates.

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, Magento added it to the message queue successfully.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "bulk_uuid": "799a59c0-09ca-4d60-b432-2953986c1c38",
    "request_items": [
        {
            "id": 0,
            "data_hash": null,
            "status": "accepted"
        },
        {
            "id": 1,
            "data_hash": null,
            "status": "accepted"
        },
        {
            "id": 2,
            "data_hash": null,
            "status": "accepted"
        },
        {
            "id": 3,
            "data_hash": null,
            "status": "accepted"
        }
    ],
    "errors": false
}