Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 30 ยท Projects

Project: Syncing Stock from an ERP

Keep Shopware stock in step with an ERP: pull or push, map and validate rows, upsert in batches, retry safely, ignore stale updates and log every rejected row.

Sooner or later a real shop meets a second system that knows how much stock exists: an ERP, a warehouse tool, a supplier feed. If that system is the source of truth, your shop must follow it. This sounds like "copy a number from A to B", yet it is where many integrations go wrong. Files arrive twice, requests time out halfway, the ERP sends a product you do not sell, and an old message overtakes a newer one.

This project builds the sync step by step: how the data gets in, how rows are mapped and validated, how writes are batched, and how the job survives retries and stale data. Before you start, it helps to know what a stock number means; Inventory Basics and Inventory Reservations cover on-hand versus available quantities, and Idempotency covers why repeats must be safe.

Shopware cannot run on this site, so the real plugin and HTTP code is read-only. Each part is followed by a plain-PHP stand-in that you can run: a mapper and a sync runner on SQLite with a fake ERP. They show the technique, not Shopware's classes.

Pull or push?

There are two ways to move the data, and the choice shapes the rest.

Pull (your plugin asks the ERP) Push (the ERP calls the shop)
Trigger A scheduled task The ERP calls the Admin API
Credentials ERP credentials in your plugin config An integration (client id and secret) in the shop
Control You decide when and how much The ERP decides; you must rate-limit and validate
Best for Nightly or hourly full snapshots Near-real-time changes
Code in the shop A plugin Often none: the ERP writes through the Sync API
flowchart LR
    ERP["ERP"] -->|"push: Sync API"| API["Admin API"]
    T["Scheduled task"] -->|"pull: HTTP client"| ERP
    T --> M["Mapper + validation"]
    API --> DAL["DAL write"]
    M --> DAL
    DAL --> DB[("product.stock")]

Both routes end in the same DAL write. Pull needs a plugin; push can use the platform's own API.

This lesson builds the pull variant because it needs code you write. Nearly everything about mapping, batching, idempotency and logging applies to the push side as well. Webhooks go the other way (the shop telling the ERP that an order was placed); that direction is covered in Apps, Webhooks and Signatures.

Absolute values make repeats safe

The most important design choice is what the message says. Compare:

  • "Stock of SW-1001 changed by -3" (a delta). If this message is delivered twice, the shop loses 6.
  • "Stock of SW-1001 is 14, as of version 5" (an absolute value). Delivered twice, the shop still shows 14.

Whenever you can choose, sync absolute quantities with a version or timestamp. Applying the same message again is then harmless, and an older message can be recognized and skipped. If the ERP can only send deltas, store the message id of every applied delta and refuse to apply one twice; that is much more work and a good reason to push back on the ERP team.

The mapper

The mapper turns ERP rows into DAL payloads. It is a pure function of its input, which makes it the best-tested class in the plugin. It has four jobs: normalize the key (trim, upper-case), reject what is invalid, collapse duplicates, and find the product id for each SKU.

PHP
<?php declare(strict_types=1);

namespace Acme\ErpSync\Service;

final class StockMapper
{
    /**
     * @param list<array{sku?: mixed, qty?: mixed, version?: mixed}> $rows
     * @param array<string, string> $productIdsBySku
     *
     * @return array{payloads: list<array{id: string, stock: int}>, rejected: list<string>}
     */
    public function map(array $rows, array $productIdsBySku): array
    {
        // validate, normalize, deduplicate; see the runnable stand-in below
    }
}

The ids come from one search for the whole batch, not one query per row. In the DAL that is a criteria with an EqualsAnyFilter on productNumber, asking for ids only:

PHP
$criteria = new Criteria();
$criteria->addFilter(new EqualsAnyFilter('productNumber', $skus));
$criteria->setLimit(count($skus));

$result = $this->productRepository->searchIds($criteria, $context);

searchIds() returns ids without hydrating entities, which is what you want here. To map ids back to product numbers you either search entities with a minimal addFields/projection or select id and product_number with a small DBAL query. Whichever you pick, do it once per batch of, say, 200 SKUs (see Reading and Writing with Repositories).

Try it: map and validate rows

The stand-in below has no database: it shows the rules. Rows that cannot be used are collected with a reason, because an empty "something went wrong" log helps nobody.

PHP A stock mapper that explains its rejects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Read the result carefully. The padded lowercase SKU matched, the numeric string became an integer, and the older duplicate for SW-1001 (version 4) lost against version 5. Note one subtle choice: when a product appears twice, the mapper keeps the highest version, not the last row. Row order in a feed is rarely a promise.

Writing in batches

With the payloads ready, the write is one call per batch. Use update() when products must already exist (you do not want an ERP typo to create a product), and upsert() only when creating is part of the job.

PHP
foreach (array_chunk($payloads, 100) as $chunk) {
    $this->productRepository->update(
        array_map(static fn (array $p) => ['id' => $p['id'], 'stock' => $p['stock']], $chunk),
        $context,
    );
}

Chunking keeps each write transaction small and limits what a failure costs. After writes, Shopware updates derived data such as available stock, and may need the product indexer to run. For large batches this indexing is the slow part, so read about the indexing behavior your version offers (the Sync API accepts an indexing-behavior header to queue or skip indexing; see Security and Performance). Do not set stock on products with variants without thinking: the stock belongs to the variant that is actually sold.

A push-style ERP writes the same thing through the Sync API, one request for many products:

HTTP
POST /api/_action/sync
Authorization: Bearer <token>
Content-Type: application/json

{
  "erp-stock": {
    "entity": "product",
    "action": "upsert",
    "payload": [
      { "id": "0190a1b2c3d44e5f8a6b7c8d9e0f1a2b", "stock": 14 },
      { "id": "0190a1b2c3d44e5f8a6b7c8d9e0f1a2c", "stock": 9 }
    ]
  }
}

erp-stock is just a key you choose for the operation. If the ERP only knows product numbers, it first needs a lookup step, or you offer a small custom route that accepts SKUs and does the mapping on your side.

Retries, stale data and logging

A sync job meets three kinds of trouble, and each has a standard answer.

Transient failures (timeouts, 502, 503, 429) are retried with a growing delay, a few times, and then the run fails loudly. Permanent failures (a 401, a malformed file) are not retried; retrying a wrong password only locks the account. In a scheduled task, the simplest overall retry is: the next scheduled run does it again, which only works because writes are idempotent.

Stale data is handled with the version column. Store the last applied ERP version next to the product (in a custom field or your own table) and update only when the incoming version is higher. Two overlapping runs, or an ERP that resends an old export, then cannot move stock backwards.

Logging has two audiences. Operators need one summary line per run: how many rows came in, how many were applied, unchanged and rejected, and how long it took. Developers need the details of each reject. Log rejects at warning level with the SKU and reason in the context array, and the summary at info. Never log credentials or the full ERP response body. Avoid one log line per successful row in a 50,000-row run.

flowchart TD
    F["Fetch rows"] -->|"503 or timeout"| R["Wait, retry<br/>(max 4 attempts)"]
    R --> F
    R -->|"gave up"| X["Fail the run, log error"]
    F --> M["Map + validate"]
    M --> A["Apply if version is newer"]
    A --> S["Log summary"]

Transient errors loop back through a delay; invalid rows are rejected individually and never stop the run.

Try it: a runner with retry, versions and a summary

The stand-in below uses SQLite for products and a fake ERP client that fails twice before answering. Delays are calculated and printed but not slept, so the example finishes instantly.

PHP A sync run that retries and ignores stale rows

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Look at the log: two retries with doubling delays, a first summary with applied rows, and a second summary where nothing was applied, because every version is no longer newer than the stored one. SW-1002 was never touched: the shop already held version 7 and the feed offered version 6. That is the stale-data guard working. In a real plugin, the retry delay comes from a sleep in the worker, or from re-queueing the message with a delay; do not block a web request this way.

What is real here: the ideas of absolute quantities, versions, retries, batch validation and a summary line. What is stand-in: the fake ERP, the SQLite schema, and the fact that the real plugin writes through the DAL repository, not SQL.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why prefer absolute quantities over deltas in a sync message?

    A repeated delta applies twice; a repeated absolute value is a no-op. That makes retries and re-sent files safe.
  2. 2. Which failure should NOT be retried automatically?

    Transient errors may pass on the next attempt. A wrong credential will fail every time, and repeating it can trigger lockouts.
  3. 3. What does the version check on the update protect against?

    Updating only where the stored version is lower makes out-of-order and re-sent data harmless.
  4. 4. Why use update() rather than upsert() for the stock write?

    Stock sync should only change products that exist. Creating products is a different job with different required fields.

Summary

  • Choose pull (a scheduled task) or push (the ERP calls the Admin or Sync API); the mapping, batching and safety rules are the same.
  • Sync absolute quantities with a version so repeats and late messages are harmless.
  • Map and validate in a pure class, resolve product ids with one search per batch, and report every rejected row with a reason.
  • Write in chunks with update(), and think about indexing cost for large batches.
  • Retry only transient failures with a growing delay, and end each run with a summary log line.

Next, test what you have learned in Practice Exercises with Solutions.