Why does an online order only appear after two hours?

That is how long the tracker has to report the purchase from the confirmation page itself. Only then does the import create its own row, so the same order does not count twice. Orders from the shop admin appear with the next sync.

Does XICTRAQ read my customers’ email addresses?

No. Read access to order would make them readable in Shopware, but XICTRAQ’s request only asks for name, company and customer number. Email addresses, phone numbers or postal addresses that customers enter into name or company are removed by XICTRAQ before storing.

Can I assign the same shop to several websites?

Yes, if the shop has several sales channels: each website then counts the channels of its tracker. A shop with only one channel can only be assigned to one website, otherwise every order would count twice.

What happens to cancelled and refunded orders?

Cancelled orders from the import do not count. Fully refunded ones get a refund at the time of the refund, also for a purchase captured by the tracker unless the tracker has reported a refund itself; cancelled orders get none. A tracker purchase for an order cancelled later keeps counting by default and carries the flag “Cancelled in shop”; “Cancellations: without” in the e-commerce tab leaves it out.

Shop connection (Shopware 6)

Through the Admin API of a Shopware 6 shop, XICTRAQ reads the exact patch level, on request the order status of the purchases captured by the tracker and, with the order import, the entire order history, including orders created in the shop admin. This page describes the requirements, setup, the eight read permissions of the role, the data flow, the counting rules, the handling of cancellations, share links and the error messages.

# Requirements

Shopware 6, from version 6.4 for order status and order import. The website settings show the “Shop API (Shopware 6)” box as soon as the scan has detected the shop as Shopware 6. Shopware 5 cannot be connected.
A verified domain: credentials are only sent to a website whose ownership has been proven.
The Business plan for the order import, as for the other e-commerce reports. XICTRAQ only stores name, company and customer number if the plan includes customer identification; it is part of the Business plan as well.
The owner, admin or editor role for the website: connecting, checking and disconnecting send requests to the shop. Every role that can see the website may read the status.
An Admin API reachable via https at the shop address. If it lives on a subdomain or in a subdirectory, enter the API address separately; it must belong to the website domain.

# Setup

The connection needs an integration in Shopware and, for order status and order import, a role with read permissions only. The integration never needs administrator rights.

1

Create an integration

In the Shopware Administration, create a new integration under Settings › System › Integrations, without administrator rights. Note the Access Key ID (starts with SWIA) and the Secret Access Key.
2

Create a role with eight read permissions

Under Settings › System › Users & permissions, create a new role and under “Detailed privileges” grant only “Read” for exactly the eight entries in the table below. The patch level alone needs no role.
3

Assign the role to the integration

Under Settings › System › Integrations, open the integration and give it the new role.
4

Connect in XICTRAQ

Website › Settings › Shop API (Shopware 6): enter the Access Key ID and Secret Access Key, the API address if needed, switch on “Import orders” and click “Connect”. XICTRAQ signs in to the shop right away, checks the permissions with a probe request and lists missing entries. Only access the shop has accepted is stored.

# The eight read permissions

Each entry with “Read” only. The sales_channel permission is deliberately missing: the sales channel ID is part of the order, the import does not need its name.

Entry	What XICTRAQ reads it for
`order`	Order: number, time, gross and net amount, shipping costs, tax status, currency, sales channel, language, whether it was created in the shop admin, plus the name, company and customer number of the person ordering.
`order_line_item`	Line items: label, quantity, unit and total price, type and order; from the extra data only the product number and variant.
`order_transaction`	Payments: state of the latest payment and when it changed.
`order_delivery`	Deliveries: shipping state and shipping costs.
`state_machine_state`	The technical names of the states, such as open, paid or shipped.
`payment_method`	Name of the payment method.
`shipping_method`	Name of the shipping method.
`currency`	ISO code of the currency.

For the order status in the order history alone, without import, four of these permissions are enough: order, order_transaction, order_delivery and state_machine_state. XICTRAQ then reads only the order number and the three states of the purchases captured by the tracker in the last 30 days, once a day and up to 1000 per day; if there are more, they take turns, oldest status first.

What read access to order opens technically

With read access to order, Shopware technically also makes the other customer details of the order readable, such as the email address. XICTRAQ only requests the name, company and customer number: the request limits the fields per entry, and email address, postal address, phone number, customer comment, VAT ID and campaign or affiliate codes are not requested at all. Whatever customers enter into name or company as email address, phone number, postal address or VAT ID, XICTRAQ removes before storing.

# Data flow

Backfill and ongoing sync

After switching on, XICTRAQ fetches the shop’s entire order history, from the newest to the oldest, in pages of 100 orders. The most recent periods are therefore complete first, older ones follow over several runs. After that the sync runs incrementally every ten minutes with a 15-minute overlap with the previous one; any change to an order, its payments or deliveries brings it back. Per shop and run the sync works for at most 90 seconds, and the next run continues whatever did not fit. A daily check finds orders of the last 30 days that were deleted in the shop. You see the status in the website settings under Shop API: imported orders, of which created in the shop admin, backfill status and last sync.

Matching to the tracker and two hours of waiting

If the tracker captured an order on the confirmation page, XICTRAQ matches it by order number: the exact number even weeks after the order, for example when payment comes late, a shortened number as reported by the tracker’s auto-detection only from one day before to 30 days after the order and only if exactly one order clearly fits. Then the tracker’s purchase counts, and the import adds status, line items and payment and shipping method. An online order without a captured purchase is only taken over two hours after the order, so that a late tracker report does not count twice. If the tracker purchase still arrives, it replaces the import row in the next sync. Orders from the shop admin are taken over in the next sync without waiting.

Duplicate order numbers, language, customer details

If an order carries a number that already belongs to another one, for example with a separate number range per sales channel or a reset number range, XICTRAQ stores it with the suffix “/” and the last eight characters of its shop ID; no order is dropped. Payment and shipping methods are named in the language most customers order in. XICTRAQ only stores name, company and customer number for orders of the last 365 days and clears them afterwards; the order keeps counting without them. The import creates one customer identity per customer number. If an identity from the tracker already exists for that customer number, it stays leading: the import does not create a second one, and the customer list and identified users show both as one customer with summed orders, revenue and sessions.

Without the tracker

The order import also works on a website without an embedded tracker. Analytics then opens the e-commerce area instead of only the tracking script instructions. The import never creates page views; visitor numbers, conversion rate and funnel stay empty without the tracker.

# Counting rules

An order counts once: with the tracker’s purchase if there is one, otherwise with the import row.
Import rows count in revenue, orders, average order value, finances, order history, customers, products, payment and shipping methods and in weekly and monthly reports. They do not count in conversion rate, funnel and ROAS, because no visit underlies them. Among the revenue sources they appear as “No visit (shop)”.
An order cancelled in the shop gets no import row; an existing one is removed with the next sync.
An online order whose latest payment failed or was cancelled does not count: the customer did not pay and did not see the confirmation page. If they pay later, it comes back with the new payment attempt. This rule does not apply to orders from the shop admin.
A fully refunded order from the import (payment state refunded) additionally gets a refund of the order amount at the time of the refund. If the shop reports a purchase captured by the tracker as fully refunded and the tracker has not reported a refund itself, the import adds the refund as well. Neither applies to cancelled orders: they get no refund row, and if a refunded order is cancelled later, its refund row is removed with the next sync. Partial refunds, returns and chargebacks from the import appear in the shop overview but do not reduce revenue.
The tracker’s purchase for an order that was later cancelled in the shop keeps counting in revenue by default; the shop overview lists these cases separately among the cancellations. With “Cancellations: without” XICTRAQ leaves them out, see the Cancellations section.

# Cancellations

By default the figures stay as the tracker measured them: a captured purchase counts even if the order is cancelled in the shop later. XICTRAQ flags such purchases and leaves them out on request.

How XICTRAQ recognises a cancellation: by the order state cancelled of the order the order import matched to the purchase; where it matched none, by the order state the order status fetch last read from the shop. With both switched off XICTRAQ knows of no cancellation and every purchase counts.
Flag: purchases whose order is cancelled in the shop carry the flag “Cancelled in shop” in the order history, in the latest orders and in a visitor’s timeline. The “Cancelled in shop” tile in the order history shows how many there are in the period.
Switch: “Cancellations: with” is the default. “Cancellations: without” in the e-commerce tab leaves these purchases out of revenue, orders and the other figures, and a refund for the same order as well; revenue and order cards on the dashboard have the setting “Exclude cancellations” for this. The switch does not change funnel and abandonment rate: they count visits that reached the confirmation page. Through the API the switch is exclude_cancelled=1, and the response then carries cancelled_excluded.
The switch does not affect import rows: an order cancelled in the shop never gets one.
The revenue overview also counts the revenue the tracker notes on the page view of the purchase. That note carries no order number; with “Cancellations: without” it is dropped for every session with a purchase for a cancelled order. If a session buys several times and only one order is cancelled, the note is dropped for its other orders too.

# What the shop data shows

From the imported orders XICTRAQ computes a shop overview per website and period. In the app the figures are available as cards (card picker › Analytics · E-commerce › Shop orders (import)), through the API at GET /websites/:id/shop/summary. Amounts are in cents.

Origin: orders and revenue from the tracker, from the import and, of those, from the shop admin, each with the previous period.
Order, payment and delivery states by their technical names from Shopware, with orders and revenue per state.
Cancellations with rate and the tracker purchases for cancelled orders that keep counting by default; refunds, partial refunds, returns and chargebacks.
Open payments, of which open for more than seven days, per payment method; open deliveries, of which open for more than three days, plus shipped and returned ones.
Sales channels as “Channel 1”, “Channel 2” and so on by order count, with share. XICTRAQ does not know the channel names, because the role deliberately lacks the sales_channel permission.
Tracker capture rate: the share of online orders (not created in the shop admin, not cancelled) that the tracker captured on the confirmation page, per day. It is computed from the website’s first tracker purchase; before that the rate stays empty. If it drops over three days below 80 % of its own 28-day value, XICTRAQ reports this as an insight.
Repeat buyers: customers who ordered in the period and had already ordered from this shop before (recognised by the customer number, 365 days), with their orders and revenue, next to the number of all customers in the period. As plain counts without names and only with customer identification in the plan; cancelled orders do not count.

# Share links

A share link shows the shop figures but never customer data: neither name, company and customer number from the order import nor tracker identities with name, company or customer ID. Order history, orders, customer list, identified users, timeline and visitor profile appear there without these details, and so do downloads from the share. Orders, revenue and the other figures remain.

# Sales channels

If the shop has only one sales channel, all orders count, and the shop can only be assigned to one website; XICTRAQ refuses a second website with the same shop on saving, otherwise every order would count twice. If it has several channels, it often serves several websites. Then a website only counts a channel from which this website’s tracker has already reported an order; the import does not store orders from other channels for this website. When a channel is added, a new backfill fetches its older orders. For a shop with several channels the import therefore needs the tracker on the respective website. Up to 30 channels per website are possible.

# Error messages

The status of the last sync appears in the website settings under Shop API and in the API in the field import.error. An order import error does not affect the patch level.

Code	Meaning
`order_forbidden`	The role lacks read permissions. The app lists the missing entries; add them to the role under “Detailed privileges”.
`order_timeout`	A sync was aborted for time reasons. The next one continues at the same point.
`order_server_error`	The shop responded with a server error while fetching orders.
`order_unexpected`	The shop response did not have the expected structure.
`order_too_large`	A page of 100 orders was larger than 8 MB.
`order_unsupported`	The Shopware version is older than 6.4.
`plan_required`	The account plan no longer includes the order import.
`access_denied`	Shopware rejected the access: check the Access Key ID and Secret Access Key, for example after the integration was deleted.
`no_api · redirect · blocked · dns · unreachable · timeout · server_error`	The shop or its Admin API was not reachable as expected. The order import shares these messages with the patch level.
`url_changed`	The website address no longer matches the stored shop address. Set up the connection again.

When connecting and saving

Code (HTTP)	Meaning
`not_verified (403)`	The website domain is not verified yet.
`plan_required (403)`	The account plan does not include the order import.
`import_shared (409)`	A shop with only one sales channel is already importing for another website.
`secret_required (422)`	The Secret Access Key is missing for a new Access Key ID.
`api_url (422)`	The API address is invalid, not https or does not belong to the website domain.
`too_many_attempts (429)`	More than ten requests against the shop within ten minutes.
`import_unavailable (503)`	The order import is not set up on the server yet.

Alerts of the connection

“Order import failing” (shop_import_failed) fires when the same error occurs twice in a row or the switched-on import has not completed a sync for more than 60 minutes; the next successful sync sends the all-clear. “Shop integration failing” (shop_integration_failed) concerns the daily patch level check and fires when it fails twice in a row. Both can be turned off under Settings › Notifications.

# Switching off and deleting

Switch “Import orders” off and save: XICTRAQ deletes the imported orders with line items, the import rows in the reports and the customer identities from the import. Patch level and, if switched on, order status keep running.
“Disconnect”: the stored credentials and all imported data are deleted, open alerts of the connection are closed.
“Reset analytics data” in the website settings also deletes the imported orders. If the import is switched on, the next sync fetches the order history from the shop again from the start.
Delete a single customer: deleting a visitor in analytics also covers customers from the import who belong to them through identity or a matched order; through the API you pass the customer number in the customer_number parameter of DELETE /websites/:id/analytics/visitor/:hash. XICTRAQ then clears name, company and customer number on the imported orders, deletes the import identity and blocks the customer number, so later syncs no longer store customer details or an identity for it. The orders keep counting without a customer reference. Owners and admins of the website may delete.
In Shopware: deleting the integration or removing its role ends the access immediately; XICTRAQ then reports the interruption as a connection error.

Frequently asked questions

For a shop with several channels, a website only counts the channels from which its tracker has already reported an order. As soon as the website’s tracker reports the first purchase from another channel, that channel counts as well, and a new backfill fetches its older orders.