ERP and order export

An ERP or external fulfilment system can import an order while the customer is still deciding on their offer. If the customer accepts afterwards, the Shopware order contains the add-on item but the already imported external order does not.

The optional ERP export setting prevents this sequence for one Shopware integration or dedicated Shopware Administration user account used by the ERP. In normal operation, every order becomes ready automatically: immediately when no offer applies, when an offer ends without changing the order, or after Shopware has fully processed an accepted offer. In the rare case that this processing does not finish, the order waits for review. It appears under Marketing → Cross-Selling & Upselling → ERP Export. When scheduled tasks are running and a shop sender email is configured, the scheduled check emails the configured recipients after the notification threshold.

Prerequisite: your ERP queries again

Use the setting only when the external system:

• queries all orders still eligible for import again on every run;
• normally imports an order that was absent from an earlier run;
• does not interpret an absent order as deleted or cancelled;
• uses either a Shopware integration or a dedicated Shopware Administration user account used only by the ERP, with credentials that are not shared with another system.

An import that only requests orders newer than the last imported order can permanently miss waiting orders and is not compatible.

Set-up

1. If the ERP uses integration credentials, under Settings → System → Integrations, create an integration used only by the ERP or external fulfilment system. If it signs in with a username and password, create a separate Administration user under Settings → System → Users & permissions instead. Do not use a shared administrator account.
2. Open Extensions → My extensions, find Post-Purchase Cross-Selling & Upselling, open its … menu and select Configure.
3. At the top, select All sales channels or the required sales channel. In ERP export, configure:

• Wait until the order is ready before the ERP can import it (default: Off): When this is off, the ERP can import every new order as usual. When it is on, an order for which no offer applies is ready immediately. An order with an offer becomes ready when the offer ends without changing the order or after Shopware has fully processed the accepted offer by adding the add-on item and recording any additional payment.
• Integration the ERP uses to import orders (default: none): Selects one integration whose direct order queries wait. Leave it empty when the ERP uses a dedicated Administration user instead.
• User account the ERP uses to import orders (default: none): Select the separate Administration user the ERP uses with a username and password. While an order is waiting, this account cannot find it in its order searches or Administration order module. Leave it empty when the ERP uses an integration instead. If both credentials are selected, both wait.
• Email if an order with an accepted offer does not become ready for the ERP (default: empty): Emails the configured recipients when, in a rare case, processing an accepted offer has not finished by the expected ready time. Open offers do not trigger this email. Enter one address per line. Leave empty to send no email; affected orders still appear on the ERP Export tab.
• Overdue notification threshold (minutes) (default: 15): Number of minutes before Shopware emails the configured recipients about an accepted offer that still needs review. The email is not sent before the expected ready time shown under ERP Export. Values of 0 or less use 15 minutes; values above 1,440 use 1,440 minutes (one day).

Values can apply globally and can be overridden per sales channel. A sales channel can inherit the global values. Each effective sales-channel configuration applies to one integration and/or one user account, not a list of credentials. When both are configured, both wait.

Everything that uses the same credentials receives the same filtered order view. Do not use a shared integration.

A change to the ERP switch, selected integration or selected user account ends running offers in the affected sales channels before the new setting applies.

Sequence

The extension does not use a different order status for this. Other Administration users and all other API credentials can still access the order; the selected ERP user account cannot while it is waiting. An unused offer waits for the remaining offer-link validity. If payment confirmation has already started, the wait ends after that confirmation window. With an accepted offer, the order becomes ready as soon as processing is complete. The ERP imports the ready order on its next run.

When the customer accepts an offer with a discount, the order contains a separate discount line item. To let your ERP map that line item, give it a product number in the global settings (Product number for the discount line item).

Covered API queries

The wait applies to direct reads of the Admin API order entity:

• list, detail, search and search IDs;
• aggregations;
• association routes whose final queried entity is order.

Writes are not filtered, so the ERP can perform its normal status change after import. The setting only affects the selected credential; other Administration users keep their usual order access.

In particular, the wait does not cover:

• orders returned only as embedded data under another root entity, such as a customer together with their orders;
• Sync API, Store API, Flow Builder or webhook messages;
• custom endpoints, direct SQL queries, or an export using different credentials.

Verify the external system's actual endpoint and credentials. The setting covers only the listed Admin API reads.

Configuration changes

A change to the ERP switch, selected integration or selected user account is a firm boundary. Before the new configuration takes effect, the extension ends open offers in the affected global setting or sales channel. An offer from the old configuration therefore cannot change the order afterwards.

If an accepted offer is still being processed, Shopware rejects the configuration change. Wait for the current order change to finish and save again. If the message appears again, open Marketing → Cross-Selling & Upselling → ERP Export and review the affected order. Allow its import only after verifying that the order items and grand total match the final payment or refund outcome, then save the configuration again. Deactivating the extension is also stopped in this situation.

Orders placed before the setting was enabled do not start waiting after the fact. Enabling it ends their older open offers in the affected sales channels so that those offers cannot later change an order which was already ready.

If an order query fails

The wait condition is part of the same database query that reads the order. If a database, schema or query error prevents that query from running safely, the current API request fails. The extension does not repeat it without the condition and does not return an unfiltered fallback response.

Fix the cause and let the ERP repeat its normal full run. Do not bypass the failed request with different credentials or by turning the setting off; those routes do not apply this readiness check.

ERP Export tab, notifications and review

Under Marketing → Cross-Selling & Upselling → ERP Export, authorised users can see waiting and ready orders with their progress, sales channel, expected ready time and email status. Viewing the tab and allowing an import are separate role permissions.

The scheduled check runs every five minutes (cwk_ppu.export_gate_overdue_notification). In the rare case that processing an accepted offer has not finished after both the configured threshold and its expected ready time, Shopware sends an email to the effective sales-channel recipient list. It records the send after success and retries a failed send on the next run. Open offers do not trigger this email.

Shopware can run this check through its Admin Worker while an administrator is logged in, or through dedicated scheduled-task and message-queue workers. Dedicated workers are recommended so the check also runs reliably overnight and at weekends.

Under Marketing → Cross-Selling & Upselling → Health, the extension reports:

• an enabled configuration without an existing API integration or user account;
• an accepted offer whose processing still needs review after the expected ready time.

List overdue waiting orders and inspect one order without changing anything:

bin/console cwk:ppu:export-gate --stale
bin/console cwk:ppu:export-gate <order-id>

Allow this import after review

An order that needs review does not become ready solely because the expected ready time has passed. This keeps the ERP from importing the order before you have checked it.

One overdue order can be allowed from the ERP Export row action (Allow this import) or interactively:

bin/console cwk:ppu:export-gate <order-id> --release

This is a recovery action, not a clean-up command. Before confirming it, check the order items, transactions, captures, refunds and extension logs. Verify that the final order items and grand total match the final payment or refund outcome. If you allow the import too early, the ERP can import the order before those records are complete. There is deliberately no bulk command.

Check before going live

1. Enable the setting for a test sales channel and select either the integration or the separate user account used only by the ERP.
2. Place a test order that receives an offer, and leave the offer page open.
3. Run an ERP import. The selected credential must not be able to import the order yet.
4. Decline the offer. The selected credential must be able to import the order on the next full run.
5. Repeat the test with acceptance. The ERP must receive the order with the add-on item and the new grand total.
6. Check that other API credentials and Administration users can access the order throughout. The selected ERP user account must not see it while it is waiting.

If the order arrives in step 3, the ERP probably uses a different credential or an export path that is not covered. See Health check and FAQ.