This guide helps you troubleshoot the most common issues with your Magento integration in Mintsoft. Whether orders have stopped importing, you're experiencing dispatch errors, or shipments aren't creating correctly, you'll find solutions here.
The article covers:
Order import issues and page size limits.
Orders not importing from Magento.
Dispatch errors with configurable and bundled products.
Shipment creation errors and automatic handling.
API connectivity issues.
Best practices for dealing with API issues.
Orders stopped importing
What causes this issue
This issue occurs when Magento's API page size limit is exceeded. Magento restricts the number of orders that can be requested in a single API call, with a maximum limit typically set to 300 orders. If Mintsoft requests more orders than this limit, the import will fail.
Error: {"message":"Maximum SearchCriteria pageSize is %max","parameters":{"max":300}}
When orders stop importing
Orders may stop importing even when no import errors appear in Mintsoft. This happens because:
Your Magento store is receiving a high volume of orders
The page size setting in Mintsoft exceeds Magento's API limit
Magento has automatically adjusted its API limits due to performance constraints
How to resolve this issue
Click Connect, then click Order Integrations.
Click Magento, then click Edit against the affected connection.
Click the Advanced tab.
Update the Magento 2 - Page Size When Requesting Orders field to 300.
Click Save.
Wait for the next automatic import to run.
Tip: The page size setting accepts values between 100 and 1000. If you continue experiencing issues after setting it to 300, you can adjust it to a lower value such as 200 or 100.
Understanding the page size setting
The page size setting controls how many orders Mintsoft requests from Magento in each API call. A lower value means:
More API calls are needed to import all orders
Less chance of exceeding Magento's limits
Slightly slower import times but more reliability
A higher value means:
Fewer API calls needed
Faster import times
Higher risk of exceeding limits if your store processes many orders
Additional considerations
If your integration stops importing orders and the URL becomes invalid, Mintsoft will automatically deactivate the integration to prevent further issues. Check your integration status and reactivate it after adjusting the page size setting.
If the solution doesn't work
If orders still don't import after adjusting the page size setting:
Check your Magento Ready Status is correctly configured in Mintsoft.
Verify orders in Magento have the correct status for import.
Review any error messages in the integration logs.
Contact the Mintsoft support team or raise a support ticket for further assistance.
Orders not importing from Magento
If orders aren't importing from Magento to Mintsoft, check the following.
Verify Ready Status configuration
Ensure the Ready Status field in your Magento connection matches the actual status of orders in Magento.
Check: Connect then Order Integrations then Magento finally Edit your connection.
The value is case-sensitive and must match exactly.
Check order status in Magento
Confirm your orders actually have the status you've configured as the Ready Status.
Custom statuses
If you're using custom Magento order statuses, ensure you've entered the exact status code, not the display label.
Default behaviour
If you haven't configured a Ready Status, Mintsoft looks for orders with status "processing".
Dispatch error: remote server returned error (400) bad request
What causes this issue
This error occurs specifically when dispatching orders that contain configurable products or bundled products in Magento.
When you dispatch an order in Mintsoft, the system sends shipment information back to Magento using order item IDs. However, configurable and bundled products have both:
A parent item (the main product customers see)
Child items (the specific variations or components)
By default, Mintsoft uses the child item ID (OrderItemID), but Magento sometimes requires the parent item ID (ParentOrderItemID) to create the shipment successfully.
When you'll see this error
You'll see this error message when dispatching orders:
The remote server returned an error: (400) Bad Request.
This happens regardless of which courier you're using, because the issue is with how Magento receives the shipment data, not the courier integration.
Related error messages
The ParentOrderItemID setting also resolves these related errors:
"The order item is not found"
"Cannot find order item by ID"
Shipment creation failures with no specific error message
How to resolve this issue
Click Connect, then click Order Integrations.
Click Magento.
Click Edit on the connection you want to update.
Click the Advanced tab.
Turn on the Use ParentOrderItemID in shipment notification instead of OrderItemID toggle.
Click Save.
Testing the solution
After enabling this setting:
Dispatch a test order in Mintsoft that previously failed.
Check the order in Magento to verify the shipment was created successfully.
Confirm the tracking information appears correctly in Magento.
Tip: If an order doesn't have a parent item ID, Mintsoft automatically falls back to using the standard order item ID, so this setting won't cause issues with simple products.
Understanding what this setting does
When you enable this toggle, Mintsoft changes which identifier it sends to Magento when creating shipments:
Disabled (default): Sends the child item ID (OrderItemID)
Enabled: Sends the parent item ID (ParentOrderItemID)
Magento stores both IDs during order import, but configurable products often require the parent ID for shipment creation to work correctly.
If the solution doesn't work
If you continue receiving the same error message after enabling this setting:
Verify the order in Magento contains configurable or bundled products.
Check the order imported correctly from Magento to Mintsoft.
Review the integration logs for additional error details.
Contact the Mintsoft support team or raise a support ticket for further assistance.
Shipment creation error: you can't create a shipment without products
What causes this issue
This error occurs when Mintsoft attempts to create a shipment in Magento, but one of the following situations exists:
The shipment has already been manually created in Magento.
The order status in Magento doesn't allow shipment creation.
The order has been fully shipped and closed in Magento.
The order items have been modified or removed in Magento after import.
The full error message you'll see is:
Error: API Error: {"message":"Shipment Document Validation Error(s):\nThe order does not allow a shipment to be created.\nYou can't create a shipment without products."}.
Automatic error handling
Important: Mintsoft automatically handles this error in most cases. When this error occurs, the system:
Detects the "Cannot create an empty shipment" message.
Automatically retries creating the shipment without specifying individual order items.
Adds a comment to the order: "Unable to Create Shipment in Magento specifying items now trying without items..."
You can check if automatic handling occurred by reviewing the order comments in Mintsoft. If you see this comment, the system has already attempted to resolve the issue automatically.
When automatic handling doesn't apply
The automatic retry only occurs if order items were originally included in the shipment request. If the error persists after the automatic retry, manual resolution is required.
How to resolve this issue manually
Step 1: Check Magento for existing shipments
Log in to your Magento admin panel.
Navigate to the affected order.
Check if a shipment has already been created for the order.
Verify the order status allows shipment creation.
Step 2: Check Mintsoft order comments
Open the order in Mintsoft.
Review the order comments for automatic retry messages.
If you see "Unable to Create Shipment in Magento specifying items now trying without items...", the automatic retry has already occurred.
Step 3: Adjust integration settings (if needed)
If you regularly experience this issue and automatic handling isn't resolving it, you can configure the integration to always create shipments without item details:
Click Connect, then click Order Integrations.
Click Magento.
Click Edit on the connection you want to update.
Click the Advanced tab.
Turn off the Include Order Items setting (if available).
Click Save.
Warning: Turning off the Include Order Items setting means shipment notifications to Magento won't include specific item details. This may affect inventory tracking in Magento for partial shipments.
Understanding the automatic retry process
When Mintsoft encounters this error, it follows this process:
Initial attempt: Tries to create shipment with full order item details
Error detection: Recognizes the "Cannot create an empty shipment" error
Automatic retry: Immediately retries without specifying order items
Order comment: Adds a comment to the order documenting the retry
Fallback success: In most cases, the retry succeeds and the order dispatches correctly
This automatic handling means you often don't need to take any action—the system resolves the issue itself.
Related error messages
The automatic retry logic also handles these related errors:
"Cannot create an empty shipment"
"The order does not allow a shipment to be created"
Similar shipment validation errors from Magento
If the issue persists
If orders continue failing to dispatch after automatic retry and manual checks:
Verify the order hasn't been cancelled or fully refunded in Magento.
Check the order is in a status that allows shipment creation in Magento.
Confirm the integration credentials are still valid and active.
Review whether recent changes were made to the order in Magento.
Contact the Mintsoft support team or raise a support ticket for further assistance.
API connectivity issues
API connectivity problems typically arise due to the following reasons:
Incorrect or expired API keys.
Authorisation problems on the third-party platform.
Improper configuration settings during integration.
By addressing these causes, you can restore connectivity and ensure a smooth integration experience.
Best practices for dealing with API issues
Always verify the validity of your API keys and update expired ones immediately.
Ensure proper permissions are granted when setting up API integrations. For example, Resource Access must be set to ALL for Magento.
Double-check configuration settings to avoid simple errors.
Reach out to platform-specific support teams when issues arise beyond your control.
Understanding your Magento integration settings
Order import process
Your Magento integration imports orders based on specific status criteria:
Ready Status: Only orders with this status in Magento will be imported into Mintsoft. Configure this in your Magento account settings.
Picking Status (optional): After importing orders, Mintsoft can automatically update them to this status in Magento to indicate they're being processed.
Dispatch process
When you dispatch an order in Mintsoft, the integration:
Creates a shipment in Magento with tracking information.
Sends order item details (unless configured otherwise).
Updates the order status in Magento based on your settings.
Applies automatic error handling if shipment creation fails.
Advanced settings reference
These advanced settings help you tune your Magento integration:
Magento 2 - Page Size When Requesting Orders: Controls how many orders are requested per API call (valid range: 100-1000, recommended: 300).
Use ParentOrderItemID in shipment notification instead of OrderItemID: Enables parent item IDs for configurable and bundled products (recommended: enabled if you sell these product types).
Include Order Items: Controls whether shipment notifications include specific item details (recommended: enabled unless experiencing persistent shipment errors).