ShipStation Routing Architecture: Mapping Logic & Webhook Control
1. Overview
This guide explains how ERP–Shopify–WMS integrations operate within Xoro, focusing on order flow, third-party data mapping, shipping configuration, ShipStation workflow routing, webhook behavior, migration control, error handling, and integration date management.
2. Functional Workflow
2.1 Order Flow: Shopify → Xoro → WMS / Shipping System
Step 1: Order Creation in Shopify
Customer places an order in Shopify.
Step 2: Order Import into Xoro
The order is imported into Xoro ERP.
Item numbers are validated.
Shipping details are validated.
External values are processed through mapping rules.
Step 3: Data Mapping and Validation
Before order creation:
Third-party mapping translates external values.
Item numbers are validated against the item master.
Carrier and ship service values are validated.
If validation fails, the order is blocked.
Step 4: Order Transmission to ShipStation or 3PL
After successful validation:
Orders are pushed to ShipStation or external fulfillment systems.
Shipping instructions depend on carrier and ship service mappings.
2.2 ShipStation Integration Architecture
Step 1: Identify Current Connection
Before configuration:
Confirm whether ShipStation is connected directly to Shopify.
Confirm whether Xoro is currently controlling shipping.
Validate whether Shopify Fulfillment App is active.
Configuration must not proceed without identifying the existing routing structure.
2.3 ShipStation Workflow Types
Workflow selection depends entirely on client operational requirements.
Three supported workflow structures exist:
Workflow A - Xoro Controls Shipping
Orders enter Xoro.
Xoro sends orders to ShipStation.
Shipment data flows back to Xoro.
Waves and shipment tracking are managed inside Xoro.
Workflow B - Shopify Controls Shipping
ShipStation remains connected directly to Shopify.
Shopify Fulfillment App retrieves fulfillment details.
Invoices are created in Xoro.
No shipment or wave is created in Xoro.
Workflow C - Invoice-Only Workflow
Orders do not generate sales orders in Xoro.
Invoices are generated based on fulfillment data.
Used when minimizing operational complexity is required.
2.4 Shopify Store & Source Mapping Architecture
Step 1: Identify Shopify Store Structure
Confirm whether the client operates:
E-commerce store
B2B store
POS store
Web store
Multiple operational sources under one Shopify account
Step 2: Configure Store Mapping in ShipStation
Map Shopify sources to corresponding ShipStation (Substation) stores.
Step 3: Apply Routing Filters
Filters may include:
Source name
Third-party source
Tags (e.g., Ecom, B2B)
Ship-to country
Step 4: Validate Routing Output
Test sample orders to ensure they route to the correct ShipStation store.
Improper filter configuration results in incorrect store assignment.
Store mapping must be finalized before filter logic is applied.
2.5 Filter-Based Store Routing Logic
Step 1: Define Routing Criteria
Orders may be routed based on:
Source
Third-party source
Tags
Country
Step 2: Configure Filter Logic
Assign filter rules at the ShipStation store level.
Step 3: Validate Store Split
One Shopify source may be split into multiple ShipStation stores using filter-based logic.
Incorrect filter logic causes cross-store routing errors.
2.6 Third-Party Mapping Workflow
Third-party mapping intercepts external data before sales order creation.
Process Flow
External value received (item, carrier, ship service, etc.).
System checks mapping table.
Exact match translation is applied.
Internal Xoro value replaces external value.
Order proceeds if mapping exists.
No match results in order failure.
2.7 Item Number Mismatch Resolution Flow
Mapping ensures external SKUs translate to internal item numbers.
If Shopify item numbers differ from Xoro:
Order validation fails.
Resolution options:
Creating the missing item.
Renaming external SKU.
Creating item mapping.
2.8 Carrier and Ship Service Mapping Workflow
When transmitting orders from Xoro to ShipStation or 3PL:
Carrier codes must be mapped correctly.
Ship service values must be mapped.
External systems must recognize the incoming codes.
If mapping is incomplete, transmission fails.
Shipping configuration depends on integration type.
Scenario A: Shopify Ship Service Used
Ship service value may be removed if no mapping exists.
External systems may not recognize Shopify shipping codes.
Scenario B: ShipStation / 3PL Shipping
Carrier and ship service mapping required.
Orders transmitted only after valid mapping.
2.8.1 Unit Conversion & Dimension Mapping Logic
Step 1: Configure Conversion Code
Set conversion logic for:
Weight
Dimensions
Step 2: Define Unit Mapping Example:
Pounds (ERP) → Grams (ShipStation)
Step 3: Validate Shipping Calculations
Ensure shipping rates and labels reflect correct unit conversions.
Incorrect unit mapping results in inaccurate carrier calculations
Incorrect unit configuration may cause carrier billing discrepancies.
2.9 Error Resolution & Webhook Retriggering
When validation errors occur:
Order is blocked.
Error must be corrected.
Wave must be unlocked.
Webhook retransmits order.
Fixing data alone does not resend the order.
Unlocking the wave retriggers the webhook.
2.10 Migration Workflow (Direct Shopify → Xoro Shipping Control)
When switching integration models:
Ship all pending orders.
Disable existing Shopify–ShipStation connection.
Update integration date in Xoro.
Enable new integration flow.
Orders created after the integration date follow the new workflow.
Incorrect sequencing creates duplicate orders and duplicate shipments.
2.11 Integration Date Control Workflow
Integration date determines routing:
Orders before the integration date follow the previous workflow.
Orders after the integration date follow the new workflow.
Incorrect integration date configuration:
Reprocesses previously synced orders.
Creates duplicate orders.
Creates duplicate shipments and duplicate waves.
2.12 Fulfillment Fetch Workflow
When shipping occurs outside Xoro:
Shopify Fulfillment App retrieves fulfillment data.
Fulfillment details are imported.
Invoice is created in Xoro.
This process records fulfillment but does not control shipping.
No shipment or wave is created in Xoro.
3. Core Configuration Logic
3.1 Third-Party Mapping Logic
Maps external values to internal values.
Works on exact match only.
No partial or contains matching.
Duplicate external value mappings are blocked.
Supports mapping for:
Items
Ship services
Carriers
Sales order fields
3.2 Item Master Validation Logic
Order creation requires:
External item number must exist in Xoro.
Mapping must exist if values differ.
Missing items block order creation.
Item master alignment is mandatory during onboarding.
3.3 Carrier & Ship Service Validation Rules
Shopify carrier values are not automatically recognized by ShipStation.
Carrier mismatches must be resolved before ship service mismatches.
Carrier validation occurs before ship service validation.
Errors resolve once correct mapping is applied.
Newly added carriers must be mapped immediately.
3.4 ShipStation In-App Mapping Configuration
ShipStation provides its own mapping interface.
Direct mapping between Xoro and ShipStation values.
Dropdown selection reduces configuration errors.
Preferred when ShipStation is used.
3.5 Migration Control Rules
Before enabling ShipStation through Xoro:
All existing ShipStation orders must be shipped.
Shopify–ShipStation direct connection must be disabled.
Integration date must be confirmed with the client.
Migration must be performed as a clean cutover.
Integration routing must not overlap.
3.6 Wave Processing & Webhook Logic
Orders are grouped into waves.
System behavior:
Webhook triggers only when a wave is unlocked.
Orders are not resent automatically after correction.
Manual unlock is required to retransmit orders.
Manual shipping in ShipStation should be avoided unless unavoidable.
3.7 Client Configuration Documentation Control
Each client configuration must include:
Excel documentation of all integrations.
Defined shipping workflow.
Mapping details.
Sync settings.
Documentation reduces configuration conflicts and repeated troubleshooting.
4. Transaction-Level Behavior
4.1 When an Order Is Imported
Validates item numbers.
Validates shipping values.
Applies third-party mappings.
Blocks order if validation fails.
4.2 When Mapping Exists
External values translated.
Order proceeds normally.
Internal values stored in sales order.
4.3 When Carrier, Ship Service, or Address Is Invalid
Order fails validation.
Error recorded.
Order not transmitted to external system.
Carrier must be corrected before ship service.
Order not resent until wave unlock occurs.
4.4 When ShipStation Is Controlled by Xoro
Order created in Xoro.
Carrier and ship service validated.
Order transmitted to ShipStation.
Shipment data returned to Xoro.
Invoice created if configured.
4.5 When ShipStation Is Connected Directly to Shopify
Order bypasses Xoro shipment creation.
Fulfillment App retrieves shipping data.
Invoice generated in Xoro.
No wave exists in Xoro.
4.6 When Integration Date Is Incorrect
Orders processed under both old and new workflows.
Duplicate shipments created.
Duplicate waves generated.
4.7 When Wave Is Unlocked
Webhook triggered.
Order resent to external system.
Updated data transmitted.
5. Structured Examples
Example 1: Item Number Mismatch Action: Shopify order contains SKU not present in Xoro. System Impact: Order fails validation. Sales order not created. Mapping or item creation required.
Example 2: Carrier Code Error Action: Order contains unrecognized carrier code. System Impact: Order blocked. Carrier must be corrected. Wave must be unlocked after correction.
Example 3: Migration Without Shipping Existing Orders Action: ShipStation control switched to Xoro without shipping pending orders. System Impact: Orders transmitted twice. Duplicate shipments created. Manual reconciliation required.
Example 4: Using Shopify Fulfillment App Action: Client keeps ShipStation connected to Shopify and enables Fulfillment App. System Impact: Fulfillment details retrieved. Invoice created in Xoro. No shipment or wave created in Xoro.
6. Important Rules & Constraints
Third-party mapping requires exact value matching.
Duplicate mapping entries are not permitted.
External item numbers must match or be mapped.
Carrier errors must be fixed before ship service errors.
Orders do not resend automatically after correction.
Wave unlock is mandatory for webhook retransmission.
ShipStation mapping should be configured inside ShipStation when available.
Integration date controls order processing scope.
Pending orders must be completed before switching integrations.
Integration routing must not overlap.
7. Best Practices
Validate item master alignment during onboarding.
Use third-party mapping only when no native mapping exists.
Prefer ShipStation in-app mapping for shipping configuration.
Confirm existing ShipStation routing before onboarding.
Perform migration at a defined cutover time.
Ship all pending orders before integration changes.
Always unlock waves after resolving errors.
Configure integration dates carefully to prevent duplication.
Maintain Excel documentation for each client.
Avoid mid-day integration switches.
8. Common Mistakes & Pitfalls
External item numbers are not aligned with the Xoro item master
Order validation fails and sales order is not created
Duplicate third-party mappings are created for the same external value
Mapping validation is blocked and configuration fails
Third-party mapping is used when ShipStation in-app mapping is available
Unnecessary manual configuration and increased risk of mapping errors
Carrier code error is corrected but ship service is fixed first
Order remains blocked because carrier validation occurs before ship service validation
Data is corrected but the wave is not unlocked
Order is not resent to ShipStation and remains unprocessed
ShipStation’s Shopify connection is not disabled before enabling Xoro routing
Orders are transmitted twice, causing duplicate shipments
Integration date is not updated during migration
Previously synced orders are reprocessed, creating duplicate orders and duplicate waves
Pending ShipStation orders are not shipped before migration
Orders are processed under both old and new workflows, causing duplication
Shopify shipping values are left unmapped when transmitting to external systems
Carrier or ship service mismatch errors block order transmission
Manual shipping is performed in ShipStation instead of unlocking the wave
Webhook is not retriggered and system traceability is disrupted
9. Frequently Asked Questions (FAQs)
Q1. What happens if a Shopify item does not exist in Xoro? A: The order fails. The item must be created or mapped.
Q2. Can one external item map to multiple internal items? A: No. Duplicate mappings are not allowed.
Q3. Does third-party mapping support partial matches? A: No. Only exact value matching is supported.
Q4. When should ShipStation in-app mapping be used? A: Whenever ShipStation is the connected shipping system.
Q5. Do orders automatically resend after fixing errors? A: No. The wave must be unlocked.
Q6. What should be fixed first in shipping errors? A: Carrier code must be corrected before ship service.
Q7. Is bulk upload available for third-party mappings? A: No. All mappings are created manually.
Q8. What is the Shopify Fulfillment App used for? A: It retrieves fulfillment data and creates invoices in Xoro.
Q9. What causes duplicate shipments or duplicate orders during migration? A: Pending orders not shipped, incorrect integration date configuration, or overlapping routing connections.
Q10. What triggers webhook retransmission? A: Unlocking the wave.
10. Conclusion
Following these third-party mapping, routing, migration, and webhook control rules ensures accurate order processing, reliable shipping configuration, and stable data flow between Shopify, Xoro ERP, ShipStation, and external fulfillment systems.
Proper mapping configuration, disciplined migration execution, correct error resolution sequencing, and controlled integration date management prevent order failures, duplicate shipments, and operational inconsistencies.
Adhering to these structured integration controls supports stable, predictable, and scalable shipping operations across connected systems.
Last updated
Was this helpful?