In short and in plain language
Sometimes a customer wants to change her order. The parcel should go to a new address. Or she needs more goods. Often the order is already in the stock system.
The shop must not make the change alone. It asks the stock system first. If packing has started, the change is no longer possible.
The customer gets an answer in every case. In her account she can see if the change worked or not.
A canceled order is not deleted. It gets a note. Each change goes into a list with the old and the new value. We help you set this up.
The order is already in the ERP when the customer writes: please ship to my office instead, and I need three boxes rather than two. In the shop this takes a minute, because the administration lets you edit the order. But the ERP created the sales order long ago, may have released it already, and a pick list may be waiting in the warehouse. If the change is saved only in the shop, two versions of the same order drift apart: the shop shows three boxes going to the office, the warehouse packs two for the home address. If the order is exported again, the worst case is a second sales order. This article shows how to sync changes after the export cleanly: which changes are allowed and until when, why the start of picking draws the line, what the interface in Shopware has to listen to, what a change event looks like instead of a second export, how line items are matched and cancellations handled as a status change of their own, what the customer gets back and what belongs in the audit log.
Key takeaways
- Around Black Friday and Cyber Week 2025, 52 percent of internet users aged 16 and over wanted to use the discounts (Bitkom); change requests for these orders hit sales orders the ERP has already taken over.
- An order change is a change of contract and needs both sides to agree (Section 311(1) BGB): the shop accepts it as a request and confirms only after the ERP has answered.
- Once picking has started, the ERP locks changes and replies with a reason, for example with status code 409 (RFC 9110); standard Shopware has no delivery state of its own for picking.
- When an order is edited in the administration, Shopware creates a draft version and merges it with the live version on save (Shopware documentation); interfaces therefore evaluate the live version only.
- Instead of exporting the order again, the interface sends a change event with eventId, change number, base revision and field list; line items are matched by IDs, not by product number.
- A cancellation is a status change, not a deletion (Section 146(4) AO); every change goes into the log with old and new value, and the confirmation stays archived as a business letter for six years (Section 147(3) AO).
Why changes after the export are integration work
Around Black Friday and Cyber Week, many people order within a short time. For 2025, roughly one in two, or 52 percent (Bitkom) of internet users aged 16 and over, wanted to use the reduced prices, most of them online. Anyone ordering fast in those days often spots a mistake only afterwards: an old shipping address, a wrong size, a forgotten item. The change requests then concern orders the ERP took over long ago, and they arrive in a phase in which warehouse and customer service are already busy.
The same survey shows how sensitive delivery is: when choosing an online shop, 53 percent (Bitkom) of the online shoppers surveyed say shipping and delivery are very important, just behind payment options at 54 percent (Bitkom). An address change that was confirmed in the shop but did not reach the warehouse hits exactly this point. The parcel goes to the wrong address, and the customer holds a confirmation that says something else.
Legally, a change after the contract is concluded is not an administrative step but an agreement. Changing the content of an obligation requires a contract between the parties (Section 311(1) BGB). The shop therefore must not rewrite the order unilaterally, and the customer's request becomes a change only once the merchant accepts it. Whether the contract has already been concluded at that point depends on your own terms: the confirmation of receipt that the shop has to send electronically without undue delay (Section 312i(1) BGB) is not automatically the acceptance. Technically, both cases lead to the same result: a change needs an answer. It can be accepted or rejected, and either outcome has to reach the customer.
Then there is the data situation. After the export, two systems hold the same order. The shop knows the cart, the customer account and the payment; the ERP knows the sales order, the reservation, the picking and later the delivery note and the invoice. Which side leads for which field is covered in the article on resolving conflicts in bidirectional sync. This article deals with the special case that the content of an order already exported changes, and with the process that brings this change into both systems without either of them losing something.
Which changes after the export are allowed
Not every change carries the same risk. A new phone number for the courier touches neither price nor stock; an additional line item touches both. A proven approach is to define each type of change separately: up to which order status it is allowed, what the ERP has to do for it and what the customer gets back. The table shows a typical starting point for mail order to consumers and business customers; you set the exact limits together with warehouse, customer service and accounting.
| Change | Allowed until | What the ERP has to do | Feedback to the customer |
|---|---|---|---|
| Shipping address | Start of picking | Replace the ship-to address in the sales order, recheck shipping method and shipping costs | New confirmation with the new address |
| Billing address | Creation of the invoice | Replace the bill-to address; after invoicing by correction (Section 31(5) UStDV) | Confirmation, plus the correction document if an invoice exists |
| Reduce quantity | Start of picking | Reduce the line, release the reservation, recalculate the total | Confirmation with the new total, partial refund if already paid |
| Increase quantity or add a line | Start of picking, if stock is free | Check availability, reserve, recalculate the total | Confirmation or rejection with reason, payment request for any extra amount |
| Payment method | Receipt of payment | Change the payment terms in the sales order, adjust open items | New payment information |
| Cancel the whole order | Shipment | Cancel the sales order, release the reservation, trigger the refund | Cancellation confirmation with refund method |
Two things are missing from the table on purpose: the price and the order date. Recalculating prices of an existing order is a step of its own. In Shopware, orders are recalculated only when this is triggered explicitly through the API (Shopware documentation). Anyone adding a line item therefore decides beforehand whether the price of the order date or the current price applies. After a sales weekend this is no formality, because the promotional price may no longer be active, and the customer still expects it.
For business customers, fields come into play that are rare with consumers: the customer's purchase order number, the cost center, the requested delivery date. They can usually be changed until shipment because they touch neither stock nor price, but they have to reach the delivery note and the invoice. How partial quantities are split across several delivery notes and invoices is covered in the article on partial deliveries and part invoices.
The lock from the start of picking
The most important limit is the start of picking. Until then, a change is a correction to the sales order. After that, it interferes with work in progress: goods sit in the picking cart, a shipping label may already be printed, a parcel may already be waiting at the dock. An address change that still goes through now reaches the parcel only if someone in the warehouse stops it again.
Only the ERP or the warehouse management system knows that moment; the shop does not see it on its own. In the Shopware source code, the delivery state has the values open, shipped_partially, shipped, returned, returned_partially and cancelled, and the order state has open, in_progress, completed and cancelled (Shopware source code). There is no state of its own for picking in this standard setup. The state machines can be modified through the API (Shopware documentation), but then the ERP also has to report the transition. Without feedback from the warehouse, a delivery in the shop stays open until shipment, even if it is being packed. How sales orders and status messages travel between the systems is described on the page about ERP inventory integration.
This leads to a simple rule: the ERP decides whether a change is still possible, not the shop. The shop asks before saving, the ERP checks the order status and answers. If picking is already running, it rejects the change. An HTTP interface has a fitting status code for this: 409 (RFC 9110) means that the request could not be completed due to a conflict with the current state of the target resource. The standard also says that the server should include enough information to recognize the source of the conflict (RFC 9110). For an order, that is the order status and the point in time from which the order is locked.
- A clear lock point in the ERP: an order status that reliably marks the start of picking, such as the release for picking or the printing of the pick list.
- A check before saving: the shop asks synchronously before confirming anything. A rejection after the fact means a wrong confirmation is already on its way.
- An answer with a reason: locked since when, by which order status, and which option the customer has instead.
- A path for outages: if the ERP does not answer, the shop accepts the change as a request but confirms it only once the ERP has agreed.
The fourth point is where projects tend to get stuck in practice. If the ERP is slow or briefly unreachable during the order peak, the shop must not simply apply the change itself. It accepts it as a request, shows it as "under review" in the customer account and waits for the decision. How a shop behaves when the ERP fails completely is described in the article on keeping the shop selling during an ERP outage.
Draft and live version: what the interface listens to
Shopware has a technical peculiarity that can lead to premature or duplicate messages when orders change. According to the documentation, editing an order in the administration creates a new draft version of the order, which is merged with the live version on save (Shopware documentation). As long as someone is working in the administration, two versions of the same order exist side by side. Only on save does the draft become the valid order.
For the interface, this means it may react to the live version only. The documentation's code example checks in the event whether the version ID of the context matches the live version and returns early otherwise (Shopware documentation). The ID of the live version is a fixed constant in the source code (Shopware source code). Leaving out this comparison sends the ERP every intermediate state from the administration, including one that is discarded in the end.
public function onOrderWritten(EntityWrittenEvent $event): void
{
// report only the saved live version to the ERP
if ($event->getContext()->getVersionId() !== Defaults::LIVE_VERSION) {
return;
}
// read the changeset, build the change event, put it on the queue
}For apps connected via webhooks, Shopware has offered the option onlyLiveVersion since version 6.5.7.0 (Shopware documentation). It is off by default, and then the webhook is called for every version of the entity (Shopware documentation). Anyone picking up order changes via webhook therefore sets the option explicitly. The payload of an entity.written webhook also does not contain the complete entity, because it might be outdated when delivered asynchronously, but essentially its primary key (Shopware documentation). The interface therefore reloads the current state of the order instead of relying on the payload.
Two more details matter for the sync. First, a changeset, meaning the list of changed fields with old and new value, is not added to the event automatically for performance reasons; a plugin has to request it explicitly before the write (Shopware documentation). Second, when a version is merged, all versions before it are deleted (Shopware documentation). Versioning is therefore a tool for drafts, not a change history. Anyone who later needs to prove what the order said before needs a log of their own.
A change event instead of a second export
The obvious solution is often the worst: simply exporting the changed order once more. Depending on the ERP connection, one of three things happens. The ERP creates a second sales order because it sees the order as new. Or it rejects the import as a duplicate, and the change disappears silently. Or it overwrites the existing sales order completely and loses what existed only in the ERP: reservations, storage bin, internal notes and the picking status.
A better approach is an event of its own that carries only the change and refers to the existing sales order. It contains the order number from the shop and the sales order number in the ERP, a sequential change number per order, the revision the change refers to, the changed fields with old and new value, the source and the time. A simplified example:
{
"type": "order.change_requested",
"eventId": "6f1c2e8a-4b7d-4c1e-9a52-0d3b7e5f1a90",
"orderNumber": "10482",
"erpOrderNumber": "A-55120",
"changeNumber": 2,
"baseRevision": "r1",
"source": "customer_account",
"changes": [
{ "field": "shippingAddress.street", "old": "Lindenweg 4", "new": "Am Markt 12" },
{ "lineId": "c41e", "field": "quantity", "old": 2, "new": 3 }
],
"requestedAt": "2026-11-30T09:14:05+01:00"
}Three fields carry the safety. The eventId stays the same on retries; Shopware handles its webhooks the same way, whose eventId does not change if sending is retried (Shopware documentation). The ERP can thus recognize duplicate deliveries and discard them, as described in the article on idempotency and retry strategies. The changeNumber sets the order: if change three arrives before change two, the ERP waits or requests the missing state. And baseRevision names the revision the change refers to.
The last field follows the principle of conditional requests in HTTP. A client can place preconditions on the current state of a resource and thus prevent a method from being applied to a state that has changed in the meantime; if the condition fails, the server answers with 412 (RFC 9110). Applied to orders: if the ERP has changed the sales order itself in the meantime, for example because a line is not available, the base revision no longer matches. The change from the shop is then not written over it blindly but reassessed.
Whether the event travels via webhook, a queue or middleware is secondary. What matters is that it has a type of its own and is not disguised as an order export. How events between shop and ERP are buffered is covered in the articles on webhooks and polling and on event-driven architecture. The implementation itself is typical work for middleware or custom API development.
Matching line items: quantity, new and removed lines
The trickiest part of an order change is the line items. An address is one field; a list of line items is a set of rows that can change in three ways: a row gets a different quantity, a row is added, a row is removed. The match has to assign every row in the shop to exactly one row in the ERP, otherwise each system ends up calculating a different order.
Stable line ID
Every shop line item carries its own ID, which is stored in the ERP line during the export. Matching uses this ID, not the product number.
Same product twice
The same product can appear twice in one order, for example as a purchased item and as a free gift. Matching by product number would mix up both rows.
Reduce quantity
The ERP line is reduced and the freed reservation is released. If part of it has already shipped, the quantity must not drop below the shipped quantity.
Add a line
Before creating it, the ERP checks availability and reserves. Price and tax rate come from the rule defined beforehand, not from the chance of timing.
Remove a line
The ERP line is canceled, not deleted. It stays visible with quantity zero and a cancellation note so the process remains traceable.
Cross-check totals
After the match, the interface compares net, tax and gross of both systems. A difference stops the confirmation to the customer and goes to clarification.
The total check at the end is not distrust of your own logic but the point where rounding, discounts and shipping costs come together. If the quantity of a discounted line changes, a cart discount may drop out or be distributed differently, and shipping costs may move to another tier. How differences between shop, ERP and e-invoice arise is covered in the article on rounding differences.
If the change alters the amount of an order that has already been paid, a payment follow-up arises. With fewer goods, part of the amount is refunded; with more goods, an additional payment or a new authorization with the payment provider is needed. Both belong to payment and accounting as separate transactions, as described in the article on payment reconciliation with the ERP. A change that increases the amount is confirmed only once the payment is settled.
Cancellation as a status change of its own
A cancellation before shipment is the most far-reaching change and at the same time the simplest one if it is modeled correctly. The mistake that keeps appearing in interfaces is deletion: the order disappears in the shop or in the ERP, and the other side learns nothing about it or later finds a sales order without a counterpart.
Shopware handles cancellation as a state: order and delivery each have the state cancelled (Shopware source code). When an order is placed, at least three distinct state machines start, for the order, the payment and the delivery (Shopware documentation). A cancellation is therefore a transition in these machines and not a deletion. The interface transmits it exactly that way: as a status change with reason and time, to which the ERP responds by canceling its sales order.
From a tax perspective, too, deletion is the wrong path. A booking or record must not be altered in a way that the original content can no longer be determined (Section 146(4) AO). A canceled sales order therefore stays in place with a cancellation note. If an invoice has already been created, a correction document follows instead of deleting the invoice; invoices and correction documents must be kept for eight years as accounting vouchers (Section 147(3) AO). Which system creates the invoice, and therefore the correction document, is covered in the article invoice from shop or ERP.
A cancellation at the customer's request also has to be kept apart from a withdrawal. In distance contracts, consumers generally have a right of withdrawal, and the withdrawal period is 14 days (Section 355(2) BGB). A merchant who rejects a cancellation before shipment may get the goods back anyway, only later and with shipping in both directions. Whether a cancellation is accepted as a goodwill gesture or treated as a withdrawal is a business decision; technically, the interface should know both paths. The withdrawal as a record of its own is described in the article on the online withdrawal function.
- The customer or customer service requests the cancellation in the shop; the shop asks the ERP for the order status.
- If picking has not started yet, the ERP cancels the sales order and releases the reservations.
- The ERP reports the cancellation back; only then does the shop set order and delivery to canceled.
- The payment is refunded or the authorization released, as a separate transaction referring to the order.
- The customer receives a cancellation confirmation, and the customer account shows the order as canceled with a date.
- If picking is already running, the ERP rejects the request, and the customer learns how a return works after delivery.
Feedback to the customer account
For the customer, what counts in the end is what she sees. A change has three possible states: requested, applied, rejected. Each of them belongs in the customer account and in a message. Confirming only the success case leaves the customer in the dark when a change is rejected, and that is exactly when she picks up the phone.
For requested changes, clear wording helps: the change has been received and is being reviewed, and it becomes binding only with the confirmation. This matches the legal situation, because a change of contract needs both sides to agree (Section 311(1) BGB). It also protects against a typical mistake in this process: the premature confirmation that did not reach the warehouse.
The confirmation itself is more than a notification. In commercial dealings, a changed order confirmation is usually a commercial or business letter. Copies of business letters sent must be kept for six years for tax purposes (Section 147(3) AO), and commercial law sets the same period of six years for business letters (Section 257(4) HGB). The message to the customer therefore belongs in the archive with its content and time of sending, not only in the mail server's delivery log.
In the accounts of business customers, a change history per order pays off: which change was requested when, whether it was applied and with which reason it was rejected. How the order status from the ERP reaches the customer account in real time is covered in the article on live order status from the ERP. If the billing address changes only after invoicing, it is not enough to swap the address in the account: an invoice with incorrect details is corrected by a document that refers specifically and unambiguously to the invoice (Section 31(5) UStDV).
The change log
Because Shopware deletes older versions when merging, versioning is no record of content changes. Shopware does keep state transitions in a history of their own with the old and new state (Shopware source code), but a changed address or quantity does not appear there. And because the ERP usually shows only the current sales order, often only a change date remains there. The log therefore belongs in the interface or the middleware, as a list of immutable entries per order. An entry contains:
- Order number from the shop, sales order number in the ERP and change number
- Source of the change: customer account, customer service, administration or ERP
- Changed fields with old and new value, for line items with the line ID
- Answer from the ERP: applied or rejected, with reason and order status
- Timestamps of request, decision and confirmation to the customer
- Reference to the confirmation sent and, where applicable, to correction documents
Such a log serves two purposes. It makes questions answerable when a customer wants to know why her change did not arrive. And it meets the requirement that the original content of a record must remain determinable (Section 146(4) AO). Where the interface appears in the process documentation is covered in the article on GoBD process documentation for interfaces.
The log contains addresses and thus personal data. It therefore needs a defined retention period that follows the retention obligations, a limited group of readers and no more fields than necessary. For troubleshooting, the ID of the change is usually enough; the full address does not have to appear in every technical log if it is in the change log.
Rolling it out in six steps
Define change types
Shipping address, billing address, quantity, additional line, payment method and cancellation: for each type, the limit in the order status and the feedback to the customer, agreed with warehouse, customer service and accounting.
Mark the lock point in the ERP
Determine the order status from which picking runs and make it queryable through the interface, synchronously and with a short response time.
Listen to the live version
Evaluate events and webhooks in Shopware for the live version only, request the changeset specifically and reload the current state of the order.
Build the change event
A separate event type with eventId, change number, base revision and field list, processed idempotently in the ERP and rejected on conflict.
Match lines and payment
Matching via line IDs, a total check after every change, partial refunds and additional payments as separate transactions.
Log and tests
An immutable change log with a retention period, plus test cases for every type of change and for the case that the ERP does not answer.
Shipping address, billing address, quantity, additional line, payment method and cancellation: for each type, the limit in the order status and the feedback to the customer, agreed with warehouse, customer service and accounting.
Determine the order status from which picking runs and make it queryable through the interface, synchronously and with a short response time.
Evaluate events and webhooks in Shopware for the live version only, request the changeset specifically and reload the current state of the order.
A separate event type with eventId, change number, base revision and field list, processed idempotently in the ERP and rejected on conflict.
Matching via line IDs, a total check after every change, partial refunds and additional payments as separate transactions.
An immutable change log with a retention period, plus test cases for every type of change and for the case that the ERP does not answer.
If you want to adapt the interface before the next sales week, do not schedule the new change process for that week itself. A change freeze on interfaces during the sales days is a proven measure, as the article on the Black Week order peak describes. The rules from this article can also be introduced afterwards, because change requests for sales orders only arise once the order has been placed. With connections to SAP or JTL-Wawi, what differs is mainly where the order status is queried; the principle stays the same.
Ask first, confirm second
Related Articles
Fixing rounding differences between shop, ERP and e-invoice
Avoid cent gaps between shop, ERP and e-invoice: what EN 16931 rule BR-CO-17 requires, VAT per line or per total, discounts, leading system and test cases.
Bulk Import from the ERP: Using the Shopware Sync API
Bulk import from the ERP into Shopware: the Sync API with upsert and delete, package sizes set by server limits, indexing via the message queue and delta sync.
Black Week order peak: preparing your ERP interface
Black Week 2026: prepare the order flow between shop and ERP – measure the backlog, move night jobs, add a queue with alerts, freeze changes, define a fallback.