Implementing Product Pagination via the Shopware 6 Store API

Solving the Over-fetching Problem in Headless Commerce

When building a headless frontend for Shopware 6, requesting an entire product catalog in a single API call leads to slow page loads, high memory consumption on the server, and potential timeouts. The solution is to implement server‑side pagination using the limit and page parameters within the Store API’s criteria system.

By shifting the pagination logic to the Shopware Data Abstraction Layer (DAL), the server only processes and transmits the specific subset of products needed for the current view, while providing the metadata required for the frontend to render pagination controls (e.g., "Page 1 of 10").

The Pagination Mechanism

Shopware 6 uses a Criteria object to handle filtering, sorting, and pagination. In the Store API, this is translated into request parameters. The limit defines how many items are returned per request, and the page defines the offset (starting at 1).

Example Configuration: Fetching the Second Page of Products

To retrieve the second set of 10 products from a category, send a POST request to the product listing endpoint. This requires a valid sw-access-key in the header.

# Request
POST /store-api/product
Headers:
  sw-access-key: YOUR_STORE_API_KEY
  Content-Type: application/json

Body:
{
  "limit": 10,
  "page": 2,
  "filter": [
    {
      "type": "equals",
      "field": "categoryId",
      "value": "018b1234567890abcdef1234567890ab"
    }
  ]
}

Analyzing the Response Structure

The API does not just return an array of products; it returns a collection wrapped in a metadata object. This is critical for calculating the total number of pages on the client side.

Field	Purpose	Usage
total	Total count of matching products	Math.ceil(total / limit) to find total pages
elements	The actual product data	Iterate through this array to render product cards

Operational Limits and Performance Risks

While pagination is efficient, certain implementation patterns can degrade performance:

• Deep Pagination: Requesting very high page numbers (e.g., page 500) forces the database to scan and skip thousands of rows before reaching the target set. This increases query execution time linearly.
• Excessive Limits: Setting a limit value that is too high (e.g., 500+) can cause memory exhaustion during the JSON serialization process or trigger a 504 Gateway Timeout.
• Caching Stale Data: If you use a caching layer (like Varnish or Redis) for API responses, paginated results may become stale. Ensure your cache invalidation strategy accounts for product price or stock changes.

Verification and Testing

To verify your pagination implementation, follow these diagnostic steps using a tool like Postman or cURL:

1. Baseline Check: Request limit: 10, page: 1. Note the first product's ID and the total value.
2. Offset Check: Request limit: 10, page: 2. Ensure the first product ID in this response is different from the first product in page 1.
3. Boundary Check: Request a page number that exceeds the total (e.g., if total is 50 and limit is 10, request page 6). The elements array should be empty, but the request should return a 200 OK status.

Rollback and State Changes

Because the Store API is a read‑only interface for product retrieval, these operations do not change the state of the database. No rollback is required for pagination requests.