DEV Community

Magevanta
Magevanta

Posted on • Originally published at magevanta.com

Magento 2 REST API Performance: Bulk Endpoints, Async Operations & Optimization

#magento #php #performance #api

If you're integrating an ERP, a PIM, or a third-party service with your Magento 2 store, the REST API is probably your first instinct. It's convenient, well-documented, and powerful. It's also one of the easiest ways to accidentally bring your store to its knees.

Slow API calls, thousands of individual product updates per hour, token generation overhead on every single request — these are patterns we see constantly in real-world Magento deployments. This guide will show you how to avoid the most common pitfalls and get serious performance out of the Magento 2 REST API.

Why Magento 2 API Performance Matters

Unlike a frontend page load, API performance issues are invisible to end users — right up until they aren't. A sync process that creates 500 products one-by-one can:

  • Max out PHP-FPM workers, starving frontend visitors of threads
  • Trigger thousands of reindex events in rapid succession
  • Lock database tables, causing checkout timeouts
  • Spike CPU usage and exhaust connections in MySQL

The REST API doesn't have a separate resource pool by default. Every /rest/V1/products call is a full Magento bootstrap hitting the same stack as your storefront.

1. Use Bulk Endpoints Instead of Looping Single Calls

The biggest mistake in Magento API integrations is making individual calls in a loop. Most developers do this:

# Terrible: 500 separate HTTP requests
for product in products:
    POST /rest/V1/products { product data }
Enter fullscreen mode Exit fullscreen mode

Magento 2.3+ ships with Async Bulk REST endpoints that batch operations into a single request and process them via message queues:

# Good: One HTTP request, processed async
POST /rest/async/bulk/V1/products
Content-Type: application/json

[
  { "product": { "sku": "PROD-001", "price": 29.99 } },
  { "product": { "sku": "PROD-002", "price": 49.99 } },
  { "product": { "sku": "PROD-003", "price": 19.99 } }
]
Enter fullscreen mode Exit fullscreen mode

The endpoint returns immediately with a bulk_uuid and queues the operations for processing by Magento's message queue consumers. Your integration gets a 200 response in milliseconds instead of waiting for 500 sequential database writes.

Bulk Endpoint Format

The pattern for bulk async endpoints is:

POST /rest/async/bulk/V1/{resource}
Enter fullscreen mode Exit fullscreen mode

This works for most standard endpoints:

  • /rest/async/bulk/V1/products — create/update products
  • /rest/async/bulk/V1/inventory/source-items — update stock
  • /rest/async/bulk/V1/orders/{id}/ship — create shipments
  • /rest/async/bulk/V1/customers — create/update customers

Checking Bulk Operation Status 

GET /rest/V1/bulk/{bulkUuid}/status
Enter fullscreen mode Exit fullscreen mode

Returns per-operation status so you can retry any failed items without reprocessing the whole batch.

2. Stop Generating New Tokens on Every Request

Integration tokens are expensive — Magento goes through a full authentication flow including database lookups and password hashing. We've seen integrations that generate a new token before every single API call. At 1000 calls per hour that's 1000 unnecessary auth cycles.

Cache your tokens. Integration tokens are valid for 1 hour by default (configurable). Store the token and reuse it until it expires:

class ApiClient
{
    private ?string $cachedToken = null;
    private int $tokenExpiry = 0;

    public function getToken(): string
    {
        if ($this->cachedToken && time() < $this->tokenExpiry - 60) {
            return $this->cachedToken;
        }

        $response = $this->http->post('/rest/V1/integration/admin/token', [
            'username' => $this->username,
            'password' => $this->password,
        ]);

        $this->cachedToken = $response->body;
        $this->tokenExpiry = time() + 3600; // 1 hour
        return $this->cachedToken;
    }
}
Enter fullscreen mode Exit fullscreen mode

For production integrations, store the token in Redis with a TTL of 55 minutes (5-minute safety margin). Multiple workers will then share the same token instead of each generating their own.

You can also adjust the token lifetime in Stores → Configuration → Services → OAuth → Access Token Expiration.

3. Increase Token Lifetime for Long-Running Processes

The default 1-hour token lifetime is often too short for batch jobs. You can increase it under:

Stores → Configuration → Services → OAuth → Access Token Expiration
Enter fullscreen mode Exit fullscreen mode

For dedicated integration users, setting this to 24 hours or even longer (set to 0 for no expiration) eliminates token refresh overhead entirely. Just be sure to rotate credentials periodically and revoke tokens for retired integrations.

4. Enable Response Compression

Most Magento 2 API responses are uncompressed by default. A product listing response with 100 products can easily be 200–400KB of JSON. Enable gzip compression in Nginx:

# /etc/nginx/conf.d/magento.conf
gzip on;
gzip_types application/json text/plain application/xml;
gzip_min_length 1024;
gzip_comp_level 6;
Enter fullscreen mode Exit fullscreen mode

Make sure your integration client sends Accept-Encoding: gzip — most HTTP libraries do this automatically. For large product catalogs, this alone can reduce API transfer time by 70–80%.

5. Use fields to Limit Response Payload

Magento supports field filtering on GET requests via the fields parameter. Instead of getting 80+ fields back for every product, ask only for what you need:

# Returns full product objects (heavy)
GET /rest/V1/products?searchCriteria[pageSize]=100

# Returns only sku, price, and qty (fast)
GET /rest/V1/products?searchCriteria[pageSize]=100&fields=items[sku,price,extension_attributes[stock_item[qty]]]
Enter fullscreen mode Exit fullscreen mode

This reduces both the SQL query complexity (fewer EAV attribute joins) and the response payload size. For inventory-only syncs, this can be a 10× improvement.

6. Tune searchCriteria for Efficient Queries

Every GET /rest/V1/products call with searchCriteria translates to a MySQL query. Poorly constructed criteria can result in full table scans.

Avoid unindexed fields in filters:

# Slow — no index on created_at for most product queries
GET /rest/V1/products?searchCriteria[filterGroups][0][filters][0][field]=created_at&...
Enter fullscreen mode Exit fullscreen mode

Better — filter on indexed fields:

# Fast — sku and entity_id are indexed
GET /rest/V1/products?searchCriteria[filterGroups][0][filters][0][field]=sku&searchCriteria[filterGroups][0][filters][0][value]=PROD-%&searchCriteria[filterGroups][0][filters][0][condition_type]=like
Enter fullscreen mode Exit fullscreen mode

For large catalogs, always:

  • Filter by indexed fields where possible (sku, entity_id, type_id)
  • Use pageSize + currentPage for pagination instead of loading everything at once
  • Implement cursor-based pagination using entity_id greater-than filters for more predictable performance

7. Run Async Consumers on Dedicated Workers

If you're using the bulk async API, make sure your message queue consumers are actually running:

# Check running consumers
ps aux | grep queue:consumers:start

# Start a consumer for async operations
bin/magento queue:consumers:start async.operations.all --max-messages=10000 &
Enter fullscreen mode Exit fullscreen mode

In production, manage consumers with Supervisor to ensure they restart on failure:

# /etc/supervisor/conf.d/magento-async.conf
[program:magento-async]
command=php /var/www/html/bin/magento queue:consumers:start async.operations.all --max-messages=10000
directory=/var/www/html
autostart=true
autorestart=true
stderr_logfile=/var/log/magento-async.err.log
stdout_logfile=/var/log/magento-async.out.log
Enter fullscreen mode Exit fullscreen mode

Without running consumers, bulk API calls queue up indefinitely and nothing gets processed.

8. Disable Synchronous Reindexing During Bulk Operations

By default, Magento may trigger index updates after each API write. For bulk imports, this is catastrophic. Switch your affected indexers to scheduled mode before running large syncs:

# Switch to scheduled (async) reindexing
bin/magento indexer:set-mode schedule cataloginventory_stock catalog_product_price

# Verify
bin/magento indexer:show-mode
Enter fullscreen mode Exit fullscreen mode

Run a full reindex after your bulk operation completes:

bin/magento indexer:reindex
Enter fullscreen mode Exit fullscreen mode

This alone can cut bulk import time by 40–60% for catalog operations.

9. Rate Limit Inbound API Traffic

If you can't control what third parties send, protect your stack with Nginx rate limiting:

limit_req_zone $binary_remote_addr zone=api:10m rate=30r/s;

location /rest/ {
    limit_req zone=api burst=50 nodelay;
    limit_req_status 429;
    # ... rest of config
}
Enter fullscreen mode Exit fullscreen mode

This prevents a rogue integration from flooding your API and starving frontend visitors of PHP workers.

Quick Reference: API Performance Checklist

Issue Fix
Looping single creates/updates Use /rest/async/bulk/V1/{resource}
Token generated on every call Cache token in Redis with 55min TTL
Large response payloads Add &fields=items[sku,price] to requests
Full reindex on every write Switch indexers to schedule mode
Consumers not running Set up Supervisor for async.operations.all
No compression on responses Enable gzip in Nginx for application/json
Unprotected API endpoint Add Nginx limit_req rate limiting

Putting It Together

For a typical ERP integration syncing 5000 products per hour, the difference between naïve and optimized approaches is staggering:

  • Naïve approach: 5000 HTTP requests × ~200ms each = ~17 minutes, 5000 reindex triggers, PHP workers saturated
  • Optimized approach: 50 bulk requests × ~50ms each = ~3 seconds, 1 reindex run after sync, zero frontend impact

The REST API is powerful when used correctly. Batch aggressively, cache tokens, compress responses, and keep your index consumers running — your integration performance will follow.

Top comments (0)