# ShipStation Order Safeguards: SKU Handling & Shipment Protection

### 1. Overview

This document defines the configuration controls, order routing rules, synchronization behaviours, and operational safeguards governing ShipStation integration with Xoro and Shopify.

It covers SKU validation, default SKU recovery, export control settings, shipment blocking rules, wave handling, tax synchronization, order filtering, carrier mapping, multi-store routing, and live confirmation behavior.

***

### 2. Functional Workflow

#### 2.1 SKU Validation & Order Drop Behavior

**System Behavior**

* Orders fail in Xoro when item numbers are missing or unmapped.
* Shopify SKU must match or be mapped to a Xoro item number.
* Blank SKUs in Shopify line items cause order failure.
* Shopify does not update SKU on existing orders after creation.

**Result**

* Orders with blank SKU will not drop into Xoro.
* SKU must exist at order creation time.

***

#### 2.1.1 Block SKU Handling

**Step 1: Configure Block SKU**

* Define specific SKU(s) to block.

**Step 2: Process Order**

* Blocked SKU is excluded from shipment.

**Step 3: Continue Order Processing**

* Remaining SKUs in the order proceed to ShipStation.
* Block SKU affects items only, not entire orders.

***

#### 2.2 Default SKU Recovery Workflow

**Purpose**

* Temporary recovery of orders with missing or invalid SKU.

**Process**

* Default SKU is configured.
* Order is rerun.
* System assigns default SKU to missing line items.
* Order successfully drops into Xoro.

**Post-Recovery Requirement**

* Default SKU must be removed from configuration immediately after recovery.

**Control Rule**

* Default SKU is a temporary recovery mechanism — not a permanent solution.

{% hint style="info" %}
This applies only to ShipStation → Xoro synchronization and does not affect Xoro → ShipStation sync.
{% endhint %}

***

#### 2.3 Default SKU Restriction from ShipStation / 3PL

**Risk**

* Default SKU items may unintentionally flow to ShipStation or 3PL.

**Control**

* Block placeholder SKUs from export.
* Restrict non-inventory items from fulfillment systems.

**Requirement**

* Client approval required before enabling restrictions.

***

#### 2.4 ShipStation Export & Store Routing Control

**Configuration Options**

* Select which store(s) export to ShipStation.
* Support for single or multiple stores.
* Export logic depends on client operational structure.

**Risk**

* Incorrect store selection causes routing inconsistencies inside ShipStation.

***

#### 2.5 Quick Ship & Wave Handling Control

**Risk**

* Quick Ship inside Xoro may generate duplicate shipments when ShipStation is active.

**Required Setting**

* **"Block quick ship when ShipStation integration"** is enabled

**Purpose**

* Prevents duplicate labels, duplicate invoices and duplicate shipments

***

#### 2.6 Tax Amount Synchronization to ShipStation

**Configuration Option**

* Enable transmission of tax amounts to ShipStation.

**Control Consideration**

* Tax handling must align with client accounting preference.
* Incorrect configuration may cause billing discrepancies.

***

#### 2.7 Manual Shipment Sync from ShipStation

**Behavior**

* Shipments manually marked in ShipStation can be fetched into Xoro.
* Sync ensures shipment status consistency.

**Recommendation**

* Enable for most clients to maintain alignment.

***

#### 2.8 Wave Merge & Auto-Merge Logic

**Supported Functions**

* Manual merging of multiple waves.
* Void requests generated for merged waves.
* Auto-merge by same customer and ship-to address.

**Operational Impact**

* Reduces shipment count.
* Increases dependency on warehouse picking logic.

{% hint style="info" %}
Configuration must align with warehouse operations.
{% endhint %}

***

#### 2.8.1 Third-Party Merge Shipment Handling

**Step 1: Merge Occurs in ShipStation**

* Multiple orders are merged into a single shipment.

**Step 2: ERP Order Status Handling**

* ERP maintains separate sales orders.

**Step 3: Enable Merge Handling Setting**

* When enabled:
  * Both ERP orders are marked as shipped.
* If disabled:
  * Orders may remain open in ERP despite shipment.

***

#### 2.9 Units of Measure & Dimension Settings

**Configuration Controls**

* Weight units (pounds, ounces, etc.)
* Dimension code settings (carton/shipment related)

**Risk**

* Incorrect units may cause carrier rating errors.

***

#### 2.10 Live Ship Confirmation: Webhook vs Scheduled Sync

**Live Webhook Sync**

* Confirmation within 1–5 seconds.
* High frequency real-time updates.

**Scheduled Sync**

* Runs every 5–15 minutes.
* More stable for high volume.

**Control Rule**

* Do not enable live webhook sync for merchants processing more than approximately 500 orders per day.

***

#### 2.11 Ship Method & SKU Blocking Rules

**Supported Controls**

* Block specific ship methods (Pickup, Own Truck).
* Block specific SKUs from export.

**Current Behavior**

* Blocking applies at order level (pending confirmation with development).

***

#### 2.12 Customer-Based Order Filters

**Functionality**

* Allow only specified customers’ orders to sync.
* Comma-separated customer filtering supported.

**Use Cases**

* Phased rollout
* Controlled fulfillment segmentation
* Improper configuration may result in missed orders.

***

#### 2.12.1 Notification Configuration & Keyword Filtering

**Step 1: Configure Notification Type**

* Available options:
  * Instant error notifications
  * End-of-day summary emails

**Step 2: Define Recipients**

* Multiple recipients supported (comma-separated).

**Step 3: Apply Keyword Filters**

* Filters prevent unnecessary notifications.
* Proper configuration improves operational visibility.

***

#### 2.13 Multi-Fulfillment & Final Ship Confirmation Behavior

**When Multi-Fulfillment is Disabled**

* Ship confirmation is treated as final.
* Remaining quantities become unallocated.

**Risk**

* May cause inventory inconsistencies if misunderstood.

***

#### 2.14 Order Filters (Country, Date, Source)

**Filter Options**

* Ship-to country
* Order date
* Third-party source

**Behavior**

* Filters control operational routing — not visibility.
* Misconfigured filters silently block order flow.

***

#### 2.15 Split Quantity Handling from ShipStation

**Behavior**

* Split shipments generate multiple invoices in Xoro.
* All shipments remain tied to one wave.

**Impact**

* Affects invoicing and accounting processes.
* Enable only if operationally required.

***

#### 2.15.1 Multi-Shipment & Invoice Behavior

**Step 1: Order Contains Multiple Items**

* Single sales order may generate multiple shipments.

**Step 2: Shipment Creation**

* Each shipment generates a separate invoice in Xoro.

**Step 3: Optional Configuration**

* Multi-shipment can be disabled if client requires single-invoice behavior.
* Incorrect configuration affects accounting and reconciliation.

***

#### 2.16 Shipping Cost Markup Rules

**Supported Configuration**

* Percentage-based markup.
* Markup by order type (eCommerce, Retail, etc.).
* Multiple markup layers may exist (ERP + ShipStation).

**Control Rule**

* Avoid double markup.
* Document markup ownership clearly.

***

#### 2.17 Carrier & Ship Service Mapping

**Requirement**

* Shopify and ShipStation use different carrier and service codes.

**Process**

* Map external carrier/service codes to ShipStation equivalents.
* Mapping populated after bulk order drops.

**Control Rule**

* Mapping decisions must be client-approved.
* Mapping errors cause shipment failures.

***

#### 2.17.1 Auto-Create Carrier & Ship Service

**Step 1: Detect Missing Carrier/Service**

* If ShipStation uses a carrier/service not defined in Xoro:

**Step 2: Auto-Creation Trigger**

* System automatically creates new carrier/service during shipment processing.
* Enable only after client approval.

***

#### 2.18 Multi-Store Mapping in ShipStation

**Supported Functionality**

* Multiple ShipStation stores.
* Filter-based routing to different stores.
* Default store used if no mapping exists.

**Use Case**

* Multi-source merchants (Shopify, Amazon, etc.).
* Improves operational visibility and separation.

***

### 3. Core Configuration Logic

* SKU must exist at Shopify order creation.
* Default SKU is temporary recovery only.
* Default SKU must be removed after use.
* Quick Ship must be blocked when ShipStation is active.
* Live webhook sync unsuitable for high-volume merchants.
* Filters silently stop order flow if misconfigured.
* Carrier/service mapping must be client-approved.
* Blocking rules must be validated before production.

***

### 4. Transaction-Level Behavior

#### 4.1 When SKU Is Missing

* Order fails with “Item number not found.”
* Default SKU required for recovery.

#### 4.2 When Quick Ship Is Enabled Improperly

* Duplicate shipments may occur.
* Duplicate invoices may generate.

#### 4.3 When Live Webhook Sync Is Overloaded

* System strain increases.
* Confirmation reliability decreases.

#### 4.4 When Filters Are Misconfigured

* Orders silently fail to sync.
* No visible error may appear.

#### 4.5 When Split Shipment Occurs

* Multiple invoices created.
* Wave remains unified.

***

### 5. Important Rules & Constraints

* Shopify does not update SKU after order creation.
* Default SKU must be removed after recovery.
* Quick Ship must be blocked when ShipStation is enabled.
* Live webhook sync not recommended for high-volume clients.
* Carrier and service mappings must be verified.
* Blocking and filtering logic must be tested before go-live.

***

### 6. Best Practices

* Validate SKU integrity during onboarding.
* Confirm tax handling requirements before enabling sync.
* Document shipping markup ownership.
* Align merge settings with warehouse logic.
* Confirm unit standards before carrier activation.
* Test all filters before production.
* Obtain client approval for carrier mappings.
* Use scheduled sync for high-volume merchants.

***

### 7. Common Mistakes & Pitfalls

| Situation                                   | Result                                              |
| ------------------------------------------- | --------------------------------------------------- |
| Blank SKU in Shopify                        | Order fails with “Item number not found”            |
| Default SKU left enabled                    | Future orders incorrectly assigned placeholder item |
| Quick Ship enabled with ShipStation         | Duplicate shipments created                         |
| Live webhook enabled for high-volume client | System overload and sync instability                |
| Filters misconfigured                       | Orders silently do not sync                         |
| Carrier mapping incomplete                  | Shipment transmission fails                         |
| Blocking rules not tested                   | Orders unintentionally blocked                      |
| Double markup applied                       | Incorrect shipping charges                          |

***

### 8. Frequently Asked Questions (FAQs)

Q1. Why does Xoro show “Item number not found”?\
A: The Shopify order contains a blank or unmapped SKU.

Q2. Can Shopify update SKU after order creation?\
A: No. SKU remains unchanged once the order is created.

Q3. When should Default SKU be used?\
A: Only to recover orders with missing SKU.

Q4. Should Default SKU stay enabled permanently?\
A: No. It must be removed after recovery.

Q5. What happens if Quick Ship is enabled with ShipStation?\
A: Orders may be shipped twice.

Q6. Is live webhook shipping recommended for all clients?\
A: No. Only low-volume clients.

Q7. Can pickup orders be blocked from ShipStation?\
A: Yes, via ship method blocking.

Q8. Can orders be routed to different ShipStation stores?\
A: Yes, using multiple integrations and filters.

Q9: Does blocking a SKU block the entire order?
\
A: No, only the specified SKU is blocked; other items proceed.

Q10: Why am I seeing multiple invoices for one order?
\
A: Multi-shipment is enabled, creating one invoice per shipment.

Q11: What happens if a SKU in ShipStation doesn’t exist in Xoro?
\
A: The system replaces it with the configured default SKU.

***

### 9. Conclusion

Following these SKU validation controls, routing rules, filtering safeguards, synchronization settings, and mapping requirements ensures accurate order processing, stable shipment flow, and consistent integration behavior between Shopify, Xoro ERP, ShipStation, and external fulfillment systems.

Proper configuration of recovery mechanisms, export controls, quick ship blocking, webhook synchronization, carrier mapping, and filtering logic prevents order failures, duplicate shipments, and operational inconsistencies.

Adhering to these structured integration controls supports stable, predictable, and scalable shipping operations across connected systems.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xorosoft.com/xoroerp-1/connected-apps/xoro-shopify-implementation-deep-dive/shipstation-order-flow-and-operational-controls/shipstation-order-safeguards-sku-handling-and-shipment-protection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.