Interfaces & Inventory Management

Not covered in this guide: CSV and Excel files using Porter ( Import & Export Guide (CSV)), Marketplaces ( eBay Integration and Kaufland Integration Guides), the product feed for Google ( Google Merchant Center & Product Feed Guide), and shipping providers such as DHL or GLS ( Shipping & Delivery Guide).

You can find all integrations with inventory management and accounting systems under Settings → Interfaces → Inventory Management/ERPs/Accounting. Click to enlarge.

The add-on module for the data interfaceXONIC Premium: xoPort Datenschnittstelle

The REST API, the XML interface, the JTL connector, Billbee (Sync), and the Tricoma connection only work if the data interface is enabled. Without it, the REST API returns the error “ LICENSE_REQUIRED,” and Tools → xoPort OAuth2 Clients displays a red warning.

The store synchronizes its licenses with the XONIC license server. If this fails for 30 days, it disables the data interface and reports “was deactivated because no connection to the auth server could be established for 30 days.” Please contact us in this case.

Create an Account

1. Open Tools → xoPort OAuth2 Clients and click “Create New Client.”
2. Enter a “Client Name,” such as the name of the program or service provider.
3. Under “Permissions,” select “Read,” “Write,” or “Delete” for each area. At least one permission is required.
4. Optional: “Rate Limit (Requests/Hour)” and “Notes,” such as who is using the access.
5. Click “Create New Client” to save. The store will display the “Client ID” and “Client Secret.” The secret appears only this one time: Copy it immediately into the program that needs to log in.

An account for a price analysis tool only needs “Products: Read”; all other sections remain locked. Click to enlarge.

Select the appropriate permissions

Permissions are organized by section, such as Products, Categories, Customers, Orders, Manufacturers, Suppliers, Media, News, FAQs, CMS Pages, Contracts, Tickets, and Newsletters. They can be modified later via “Edit Permissions.”

Only assign “Delete” if a program is actually supposed to remove records.

Address and Registration

The program uses the client ID and client secret to obtain an access token. The token is valid for one hour; after that, the program requests a new one. Your store’s token address is listed in the info box under Tools → xoPort OAuth2 Clients.

curl -X POST https://ihr-shop.example/xpanel/xoport/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>"

curl -H "Authorization: Bearer <TOKEN>" \
  https://ihr-shop.example/xpanel/xoport/export/json/products?limit=250&offset=0

Each address consists of /xpanel/xoport/, the task (export, import, or delete), the format json, and the area. If any other format is used, the API returns “Unknown route.” Deletion is only possible using the method DELETE.

Retrieving data page by page: Use ` ?limit= ` (default 50, maximum 250) and ` ?offset= ` to scroll through large datasets. The response reports the total count at ` stats ` and indicates whether more pages follow at ` has_more`.

Limits

• Query limit: A new user may make 5,000 queries per hour. A higher value can only be set by XONIC after review. Anyone who exceeds the limit will receive 429 with RATE_LIMIT_EXCEEDED.from 4.9.17
• Records per import: no more than the number allowed by Settings → Interfaces → Inventory Management/ERPs/Accounting → xoPort Data Interface → xoPort API: Bulk Import Limit, which is set to 50 by default.
• Creation and modification are separate: POST creates only new records and returns the message “already exists. Use PUT to update.” if an existing item number is found. PUT modifies only existing records.

Under Settings → Interfaces → Inventory Management/ERPs/Accounting → xoPort Data Interface → xoPort: Enable Settings for the Interface, you can enable individual shop settings for the API. If no entries are made, the API will not see any. Access data, license, and login settings always remain locked.from 4.9.54

“View Usage” lists every request from a user; a 403 error indicates an access attempt outside the authorized areas. Click to enlarge.

Restrict Access to Fixed IP Addresses

Under Settings → Interfaces → Inventory Management/ERPs/Accounting → xoPort Data Interface → xoPort API: IP Restriction (JSON/REST), enter the addresses from which your programs originate. Then, every request must include both: one of these addresses and a valid token. If left blank, the REST API remains open to any access with a valid token.from 4.9.83

• Enter only individual addresses, separated by commas. A range such as 203.0.113.0/24 will never match here and will block all programs.
• If the shop is behind a proxy or Cloudflare, the address the shop sees applies. If it denies access, the response from IP_NOT_ALLOWED will list this address, and the dashboard will display “xoPort REST: Connection blocked.”
• The list in the XML interface (“xoPort: IP Filter”) does not grant access to the REST API. The REST API always requires a token.from 4.9.83

Enter only fixed addresses. If an address changes, remove the old one from the list immediately: The provider will reassign it, and its next owner would otherwise have access.

Enabling and Access

The settings in this section are located under Settings → Interfaces → Inventory Management/ERPs/Accounting → xoPort Data Interface.

• Settings → Interfaces → Inventory Management/ERPs/Accounting → xoPort Data Interface → xoPort: Enable Old XML Interface unlocks the URLs at /xpanel/xoport/. New stores start with false; existing ones retain true. On false, the addresses respond to every request with a 403 error, including those for the Tricoma connection.from 4.9.78
• Proof: The inventory management system appends the key from “xoPort: AppKey Filter” as ?key= to the address, or it calls “xoPort: IP Filter” from an address. If your Internet address changes, the key is the more reliable method. Access the addresses only via https://.
• Do not clear the “xoPort: AppKey Filter” while the XML order export is running: The export accesses your shop’s interface using this key.
• “xoPort API: Authentication Required” remains displayed at true. At false, the XML interface responds to every request without verification, and the dashboard reports “xoPort data interface is unprotected.”

Under Settings → Interfaces → Inventory Management/ERPs/Accounting → xoPort Data Interface, you’ll find the interface’s access, filter, and import settings; new stores launch without the old XML interface. Click to enlarge.

Files and Addresses

The inventory management system places its files via FTP or SFTP in the folder xoport/xml/import/. The files are only imported when the corresponding address is called up. The filename must begin exactly as shown in the table—including uppercase and lowercase letters—and end with .xml, for example, Products_2026-10-04.xml.

The shop moves imported files to the subfolder archiv/. After “xoPort: Archiving time in days” (default 14), the product or order import deletes them from there.

It moves files that cannot be read to xoport/xml/import/error/ and specifies the line and reason in the response. It removes individual invalid control characters on its own and then imports the file.from 4.9.65

The Product XML

A product file contains one element per item: <product> under <products>. The store identifies the item via model, the item number. The most important elements:

The import transfers prices unchanged into the store’s price fields; these fields contain net prices. If a file provides attributes, the import replaces all of the item’s attributes with the provided ones.If it contains none, the existing ones remain.from 4.9.21

You can specify which fields and nodes the import actually processes under Settings → Interfaces → Inventory Management/ERPs/Accounting → xoPort Data Interface → xoPort: Product Import Settings; see Import Restrictions. If your merchandise management system provides its own format, a shop-specific template (“xoPort: Custom XSL Template”) converts it into the shop’s format. This template is retained during updates.from 4.9.21

All elements—including those for categories, manufacturers, customers, and orders—are described in the API documentation.

1. The inventory management system or a cron job calls https://ihr-shop.example/xpanel/xoport/export_orders.php?key=<AppKey>.
2. For each order with a number higher than “xoPort: last exported order number,” the store writes a file named order-<Bestellnummer>.xml to the folder xoport/xml/export/. It then sets the value to the last order whose file was successfully processed. A failed order is retried during the next run.
3. The inventory management system retrieves the files via FTP or SFTP. The order files are locked via the web. It typically moves retrieved files to xoport/xml/export/archiv/.
4. It returns the status, comment, and tracking numbers via a Orders…xml; see Files and Addresses.

In the archive, the store deletes files after “xoPort: Archiving period in days.” The value “ 0 ” means: never delete. Since the files contain customer data,be sure to set a time limit.from 4.9.116

Confirmation with Status and Tracking Number

• The store identifies the status by its name, using the German designation. If it does not recognize the reported name, it creates a new order status with that name. Therefore, be sure to use the exact German status names from the store in your inventory management system.
• Whether the customer receives an email is determined by the “ customer_notified ” field in the file: “ 1 ” means “notify.”
• If the inventory management system sends the same message a second time without any other status having been reported in between, the shop will discard it. If you intentionally report a status multiple times for partial deliveries, enter its ID under Settings → General → Basic Settings → xoPort Status Import: Statuses that trigger a notification even when repeated.from 4.9.66

Porter exports orders in two steps: one Porter for the order data and a second one for the line items. For information on how these two are related and how to re-export orders, see “Exporting Orders and Customers.”

Setup

The settings are located under Settings → Interfaces → Inventory Management/ERPs/Accounting → JTL:

What is synchronized

The connector does not import tracking numbers or booked incoming payments from JTL-Wawi. You must then manage shipment tracking in the store; see Shipment Tracking. The JTL connector does not evaluate import restrictions on items.

Two stores: A connector is associated with exactly one store installation, with its own address and its own “JTL token.” Two stores therefore require two connections. However, multiple domains within a single installation share the same database and connector.

OpenXE

The page Settings → Interfaces → Inventory Management Systems/ERPs/Accounting → OpenXE connects the store via the “OpenXE API Path” and “OpenXE API Token.” Without both, it won’t import anything.from 4.9.106

• “Data Import” tab: “Products, Inventory Levels, and Categories,” “Inventory Levels,” “Customers and Representatives,” and “Tracking Data.” Each run starts in the background and displays its progress below the line. You can close the page; the run will continue.
• “Data Export” tab: Orders with the “Order Status for Export to ERP” set to “Export Orders” are saved as a file in the “Export File Directory.” Afterward, you’ll see the “Order Status After Export.” To export again, set an order back to the export status.
• The category synchronization creates new categories and moves modified ones. It leaves the status, image, sorting, and “Category as Header Tab” of an existing categoryunchanged.from 4.9.135
• If the page displays the message “Background processes are not possible on this server,” the server is missing the required PHP function. We’ll resolve this with your hosting provider.

Additional Integrations

If your inventory management system is not listed, the REST API is usually the best option: Many programs and service providers access it via their own connection or a tool like n8n.

The guides “Statistics & Reports ” and “Processing Orders” describe how to export sales data as a CSV file and print invoices in batches.

n8n

The Settings → Interfaces → Artificial Intelligence → n8n page has the tabs “Overview,” “Settings,” and “Events”:

1. Enter the “n8n Instance URL,” “Instance Type” (n8n Cloud or self-hosted), and “n8n API Key,” then click “Test Connection.”
2. Create a webhook node in n8n and enter its address as the “Webhook URL.” A “Webhook Secret” signs each message in the header X-Webhook-Signature so that n8n can recognize legitimate messages.
3. Enable “Enable Webhooks” and, in the same “Settings” tab under “Event Configuration,” select the desired events, then click “Save.” By default, none are active. The “Events” tab then displays the status, an example payload, and the most recent webhook calls.
4. “Send Test Event” checks the connection, and “Recent Webhook Calls” displays the results.

You can configure the webhook URL, secret, and the events to be reported in the “Settings” tab on the n8n page and apply the changes by clicking “Save.” Click to enlarge.

The notification contains only a few details, such as the order number, total, and payment method, or—for new customers—the name and email address. The workflow retrieves additional data using its own access via the REST API; see REST API.

The simplest option without programming: an order export via Porter and the import of tracking numbers via CSV; see Exporting Orders and Customers.

On the product page: the data interface tab

When the data interface is active, each saved product has a tab with the name of the active interface, such as “xoPort Data Interface.” There, you specify which fields for this product may be overwritten during import. If a toggle is turned off, the import leaves the field unchanged. It always imports newly created items in their entirety.

A deselected checkbox prevents this item’s field—in this case, the main price—from being imported. Click to enlarge.

• Forprice-regulated items such as books, lock them together using “Update Main Price” and “Update Tax Class.” Otherwise, a new tax class will change the gross price even if the net price is locked.from 4.9.26
• The CSV Porter takes “Update Name” and “Update Description” into account; see “Protect Fields.”
• The REST API can set the locks using the ` import_blocks ` field. However, it writes whatever it sends itself.
• The JTL Connector does not evaluate the locks.

For all items: Product Import Settings

Under Settings → Interfaces → Inventory Management/ERPs/Accounting → xoPort Data Interface → xoPort: Product Import Settings, each field of the item is listed with its technical name, and each node of the file (node_…) has a Yes/No toggle. The XML product import does not include anything set to “No” for any product. It always reads the product number and ID.

• If the merchandise management system provides a surcharge that you want to maintain in the shop, disable the corresponding field here—for example, shipping_surcharge.
• The import only creates new items if “ node_categories ” and “ node_languages ” are enabled. They are enabled by default.

Categories

In the category screen, the “xoPort Data Interface” tab contains the buttons “Update Name,” “Update Description,” “Update SEO Fields,” and “Update Category Image.” These apply to the XML category import; when creating a new category, the system imports everything from the file.

The “xoPort Filter” field

The “xoport Filter” field is located on the “Miscellaneous” tab of the product. It does not protect anything, but rather assigns the item to exports: Enter one or more keywords, separated by semicolons. A porter with the same “Export Filter” will then export only items with that keyword, and product feeds can be used to limit or exclude items.

• Where: in the customer profile, “Customer Data” tab, “Individual Customer Number (External)” field, up to 64 characters. The XML interface and the REST API populate this field during customer import; the XML customer import uses this number to find accounts.
• On receipts: With Settings → Checkout → Customer Details → Use external customer number as own customer number set to “ true ” (default), invoices and other receipts display this number instead of the customer ID. Whether the customer number appears on receipts at all is controlled by Settings → Design → Receipts → Customer Number. Guest orders do not include a customer number.
• To change the assignment: Enter the new number in the customer account. When you save, the store checks to ensure no other account already has that number; otherwise, it displays the message “The customer … already has this customer number!” Receipts retrieve the number from the account when they are generated, so a newly created receipt will show the updated number.

For more information on customer IDs and unique numbers, see the “Managing Customers” guide.

After an update to the merchandise management system, the cause is usually due to changed file names, status names, fields, or a new web address. Check the dashboard messages, “View Usage” in the access log, and the interface response. If the issue remains unclear, please send us the timestamp and the response.