> For the complete documentation index, see [llms.txt](https://docs.rishvi.co.uk/linnworks/llms.txt).
> Use it to discover all available pages before exploring further.
# Wayfair & CastleGate Integration via Rishvi Services
A secure, scalable, API-driven integration that automates order, fulfilment, shipment, cancellation, product, and stock workflows between Linnworks and Wayfair, including CastleGate and Wayfair Multi-Channel Fulfilment.
## Overview
The Wayfair & CastleGate Integration, powered by Rishvi Services, connects Linnworks with Wayfair Dropship, CastleGate, and Wayfair Multi-Channel Fulfilment. Rishvi Services acts as a secure, API-driven integration layer between the systems, handling inbound order import, outbound fulfilment, cancellations, shipment updates, product synchronisation, stock updates, and operational auditing.
### Architecture at a glance
Acts as the operational system for orders, products, postal services, stock locations, identifiers, and fulfilment processing.
Acts as the integration platform. It authorises each Linnworks installation, stores tenant-specific configuration, validates and maps data, runs scheduled jobs, and records detailed audit logs.
Supplies Dropship and CastleGate orders, accepts product inventory updates, fulfils outbound 3PL orders, and returns fulfilment, cancellation, shipment, and inventory information.
> Once configured, the integration runs automatically. Manual intervention is normally required only for configuration, service mapping, validation errors, suspended subscriptions, or support investigation.
---
## Integration Scope
The integration covers four key areas of the order and fulfilment workflow.
Imports Wayfair Dropship and CastleGate purchase orders into Linnworks and sends eligible Linnworks orders from the **CastleGate 3PL** fulfilment location to Wayfair Multi-Channel Fulfilment.
Sends eligible Linnworks inventory changes to Wayfair and updates the mapped **CastleGate 3PL** Linnworks location with fulfilment stock returned by CastleGate.
Checks Wayfair fulfilment status, writes carrier and tracking information to Linnworks, and processes shipped fulfilment-centre orders when the required shipment data is available.
Supports multiple Linnworks installations, each with its own token, Wayfair credentials, environment, feature settings, fulfilment location, service mappings, queues, and audit data.
---
## Installation Guide
Follow these steps to install and configure the Wayfair CastleGate channel in Linnworks.
### Steps to Install
**Open Channel Integrations**
1. Sign in to your **Linnworks** account.
2. Select **Settings** from the left-hand navigation menu.
3. Under **Settings**, select **Channel integration**.
4. On the **Channel Integrations** page, click **Add New**.
The **Add Channel** window opens.
**Install the Wayfair CastleGate application**
1. Search for **WAYFAIR CASTLEGATE**.
2. Confirm that the application is provided by **Rishvi Ltd**.
3. Review the application information and documentation if required.
4. Click **Install Application**.
The Wayfair CastleGate installation wizard opens.
**Enter an account name**
Enter a unique account name that will help you identify this integration in Linnworks.
1. Enter a descriptive name in **Account Name**.
2. Use a name that distinguishes this account from other Wayfair integrations.
3. Click **Next**.
The account name becomes the channel's subsource name on the Channel
Integrations page.
**Review and accept the disclaimer**
1. Read the third-party application disclaimer.
2. Review the linked terms and conditions.
3. Select **I agree to the terms and conditions**.
4. Click **Next**.
You must accept the terms and conditions before continuing.
**Select the integration profile**
1. Open the **Integration Profile** dropdown.
2. Select:
**Common Integration - Basic order and inventory sync**
3. Confirm that the correct profile is displayed.
4. Click **Next**.
The selected profile determines which configuration fields and integration
features are available in the next step.
**Configure the Wayfair integration**
Enter the Wayfair credentials supplied by your authorised administrator.
| Field | Description |
| ------------------------- | -------------------------------------------------------------------- |
| **Wayfair Client ID** | Client ID issued for the Wayfair API application |
| **Wayfair Client Secret** | Secret associated with the Wayfair Client ID |
| **Wayfair Supplier ID** | Supplier identifier used for Wayfair requests |
| **Wayfair Environment** | Select **Sandbox** for testing or **Production** for live processing |
Review the available synchronisation options:
- **Is Wayfair Order Sync**\
Imports eligible Wayfair orders into Linnworks.
- **Enable 3PL Order Sync**\
Sends eligible Linnworks orders to Wayfair Multi-Channel Fulfilment.
- **Enable 3PL Order Cancellation**\
Sends supported fulfilment cancellation requests to Wayfair.
- **Enable 3PL Order Dispatch Sync**\
Retrieves shipped fulfilment information and processes it in Linnworks.
After completing the configuration:
1. Confirm that the credentials and Supplier ID are correct.
2. Confirm that the correct Wayfair environment is selected.
3. Enable the required synchronisation options.
4. Click **Next**.
Never include your Wayfair Client Secret, password, access token, or full
credentials in documentation, screenshots, or support messages.
**Finish the installation**
When the **Finished** screen appears:
1. Confirm that the integration has been completed.
2. Click **Finish** to close the installation wizard.
Linnworks returns you to the Channel Integrations page.
**Verify the installed channel**
Confirm that the new Wayfair channel appears in the integrations list.
Verify the following:
- **Source** displays **Wayfair**
- **Subsource** displays the account name entered during installation
- **Enabled** shows that the channel is active
- **Inventory Sync** displays the expected status
- The channel-management actions are available
The Wayfair CastleGate channel is now installed and ready for operational
validation.
## How Orders Are Fulfilled
When an eligible order is available in Linnworks, the integration follows a defined sequence to submit it to Wayfair Multi-Channel Fulfilment.
Rishvi Services confirms that one active integration exists for the Linnworks installation, **Enable 3PL Order Sync** is active, the Wayfair Supplier ID is configured, and the order is assigned to the mapped **CastleGate 3PL** fulfilment location.
The integration validates and maps the Linnworks order to the Wayfair fulfilment request. Required data includes:
- **Customer information** - name and contact details
- **Delivery address** - address line 1, town or city, postcode, and country
- **Shipping information** - the applicable Linnworks postal service and mapped Wayfair values
- **SKUs** - the supplier part number selected from Channel SKU, Linnworks SKU, then Item Number
- **Quantities and totals** - ordered quantities, totals, and applicable tax data
Valid orders are submitted to Wayfair Multi-Channel Fulfilment. The integration records the Wayfair fulfilment request identifier, request result, processing state, and audit details.
A link is retained between the Linnworks order, the integration queue record, and the Wayfair fulfilment reference. This linkage is used for deduplication, cancellation, status checks, shipment processing, and support investigation.
After Wayfair accepts the request, the integration assigns **`Sent to WayfairCastleGate`** to the Linnworks order. If validation fails, it assigns **`Error from WayfairCastleGate`** and adds an internal note containing the validation errors.
> Wayfair Dropship orders and CastleGate purchase orders also flow inbound to Linnworks. They are fetched, deduplicated, queued, returned through the Linnworks channel order feed, and verified in Linnworks.
---
## Order Cancellation
If an outbound fulfilment order must be cancelled before Wayfair ships it, the integration provides cancellation handling.
When **Enable 3PL Order Cancellation** is active, Rishvi Services detects eligible Linnworks cancellations and uses the stored order linkage to submit a cancellation request for the corresponding Wayfair fulfilment order. Results are stored as **Cancelled**, **NotCancellable**, **AlreadyCancelled**, or **Failed**. Failed cancellation requests are retried only within the configured retry limit.
> Cancellation depends on the order still being cancellable in Wayfair. Once Wayfair reports the fulfilment as shipped or otherwise not cancellable, shipment processing applies instead.
---
## Shipment Tracking Updates
After Wayfair fulfils an order, Rishvi Services checks the fulfilment status and updates Linnworks with the latest shipment information.
When **Enable 3PL Order Dispatch Sync** is active, the integration checks Wayfair fulfilment statuses on a staggered five-minute cycle. Each result is recorded with timestamps, queue history, audit information, and a correlation ID.
The integration identifies the Linnworks order using the stored Wayfair fulfilment reference and processes the order when Wayfair reports **SHIPPED**.
| Wayfair Shipment Field | Linnworks Update |
| ---------------------- | ------------------------------------------- |
| Fulfilment status | Fulfilment-centre order processing state |
| Carrier | Shipping carrier information |
| Service | Shipping service information |
| Tracking number | Tracking information on the Linnworks order |
For a shipped fulfilment order, Rishvi Services:
- Reads the carrier, service, and tracking information
- Updates Linnworks shipping information
- Processes the Linnworks fulfilment-centre order
- Records audit and API log entries
- Marks the queue **ProcessedInLinnworks**
Missing or incomplete tracking data prevents successful processing and requires investigation.
Failed technical operations retain their retry count and error details. Eligible failures are retried within the configured limit. Validation or data failures must be corrected before the order can be processed successfully.
---
## Stock Synchronisation
Stock is synchronised in both directions: eligible Linnworks inventory changes are submitted to Wayfair, while CastleGate fulfilment stock updates the mapped Linnworks location.
When Linnworks submits an eligible inventory change, the integration creates an inventory operation and sends the new quantity to Wayfair.
| Environment | Inventory behaviour |
| -------------- | ---------------------------------------------------------- |
| **Sandbox** | Uses a `TRUE_UP` request in dry-run mode for testing |
| **Production** | Uses a `DIFFERENTIAL` inventory update for live processing |
The operation can finish immediately or remain **SubmittedToWayfair** when Wayfair accepts it for asynchronous processing.
The integration:
1. Retrieves CastleGate inventory-summary pages.
2. Adds fulfillable quantities across CastleGate warehouses for each supplier part number.
3. Matches the supplier part number to a Linnworks SKU exactly.
4. Writes matching quantities to the **CastleGate 3PL** Linnworks location in batches of up to 50.
5. Records fetched, matched, skipped, updated, and failed totals in the inventory audit.
A failed batch does not prevent the remaining batches from being attempted.
The CastleGate inventory job normally runs every **6 hours** when enabled. Product catalogue retrieval runs every **5 hours**, while operational audits and queue states provide a fallback for identifying missed, skipped, or failed records.
> **Current limitation:** Direct Wayfair price updates are not supported because the implemented product update flow does not expose a catalogue price field.
---
## Multi-Tenant Configuration
The integration supports multiple Linnworks installations from one platform. Each installation is treated as an independent tenant with isolated configuration and operational data.
### Per-Tenant Configuration
| Configuration Area | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Linnworks Installation** | Installation token, account details, application state, and associated portal users |
| **Wayfair Credentials** | Client ID, Client Secret, Supplier ID, and selected Sandbox or Production environment |
| **CastleGate 3PL Location** | Dedicated Linnworks fulfilment location used for outbound orders and CastleGate stock |
| **Shipping Service Mappings** | Linnworks postal service mapped to the Wayfair carrier SCAC and ship-speed values |
| **Feature Toggles** | Controls Dropship order import, 3PL order sync, cancellation, and dispatch sync |
| **Queues and Audit Data** | Tenant-specific inbound orders, fulfilment requests, cancellations, product operations, API logs, and correlation IDs |
| **Subscription State** | Controls whether protected scheduled and manual workflows can run |
### Multi-Tenant Benefits
One integration platform can serve multiple Linnworks installations without mixing orders, credentials, queues, or audit records.
Each tenant can be configured independently for Wayfair Sandbox or Production.
Order import, fulfilment, cancellation, and dispatch synchronisation can be enabled or disabled per tenant.
Linnworks and Wayfair credentials and operational data are scoped to the relevant tenant and portal permissions.
---
## Production-Readiness Features
Inbound orders, fulfilment orders, operations, cancellations, and synchronisation results are persisted so processing state survives beyond one request.
Failed operations retain their retry count and error details. Eligible technical failures can be processed again within configured limits.
Required settings and order data are checked before submission. Validation failures are written to Linnworks and surfaced in the portal for correction.
Wayfair order references, CastleGate purchase-order numbers, fulfilment references, and Linnworks identifiers prevent normal scheduler cycles from creating duplicate records.
Correlation IDs connect queue history, audit entries, and API logs so a transaction can be traced across systems.
Protected workflows check installation activity, feature settings, and subscription state before processing.
**Automation Schedule**
All scheduler times are defined in **UTC**.
| Workflow | Normal schedule |
| --------------------------------------------- | ------------------------------------------------ |
| Wayfair Dropship order fetch | Every 5 minutes |
| CastleGate purchase-order fetch | Every 10 minutes |
| Linnworks 3PL order fetch | Every 5 minutes |
| Send 3PL orders to Wayfair | Every 5 minutes, staggered 2 minutes after fetch |
| Cancel eligible 3PL orders | Every 5 minutes, staggered after send |
| Sync shipped Wayfair fulfilments to Linnworks | Every 5 minutes, staggered after cancellation |
| Wayfair supplier-catalogue product fetch | Every 5 hours |
| Verify inbound orders in Linnworks | Hourly |
| CastleGate inventory to Linnworks | Every 6 hours when enabled |
| Subscription check | Sunday at 02:00 UTC |
| Linnworks order-identifier sync | Daily at 03:00 UTC |
---
## Support Portal
The support portal provides operational visibility and controlled management tools for the integration.
### What Support Users Can Do
Review installation state, integration configuration, Wayfair environment, feature settings, and subscription state.
Map Linnworks postal services to the required Wayfair carrier SCAC and ship-speed values.
Search inbound queues, outbound fulfilment queues, cancellations, product operations, stock-sync audits, API logs, and correlation IDs.
Inspect validation errors, failed operations, retry counts, payload history, and exact failure messages.
Authorised users can trigger supported fetch, send, retry, or synchronisation actions after the underlying issue is corrected.
Review timestamped installation, configuration, user, email, order, product, stock, and API activity.
Before escalating an issue, collect the installation ID or email, integration ID, Linnworks order ID and reference, Wayfair purchase-order or fulfilment request ID, current queue status, exact error text, correlation ID, and UTC timestamp.
---
## Order Lifecycle
Orders use different status groups depending on whether they are inbound to Linnworks or outbound to Wayfair fulfilment.
| Status | Description |
| ----------------------- | ------------------------------------------------------------- |
| **Pending** | Stored by the integration and waiting for Linnworks retrieval |
| **SentToLinnworks** | Returned to Linnworks through the channel order feed |
| **VerifiedInLinnworks** | Confirmed in Linnworks open orders |
| Status | Description |
| ------------------------ | --------------------------------------------------------- |
| **Pending** | Linnworks order is queued for Wayfair submission |
| **InProgress** | Submission is currently running |
| **Completed** | Wayfair accepted the fulfilment order |
| **Failed** | A non-validation failure occurred and attempts may remain |
| **ValidationFailed** | Order data must be corrected in Linnworks |
| **ReadyForRetry** | Corrected order is eligible for another attempt |
| **Cancelled** | Fulfilment order has been cancelled |
| **ProcessedInLinnworks** | Shipped fulfilment was applied and processed in Linnworks |
| Status | Description |
| -------------------- | -------------------------------------------------- |
| **NotRequested** | No cancellation has been requested |
| **Pending** | Cancellation is queued |
| **InProgress** | Wayfair cancellation request is running |
| **Cancelled** | Wayfair confirmed cancellation |
| **NotCancellable** | Wayfair reports that the order cannot be cancelled |
| **Failed** | Cancellation attempt failed |
| **AlreadyCancelled** | Wayfair had already cancelled the order |
### Lifecycle flow
An eligible Linnworks order assigned to **CastleGate 3PL** is identified and queued for outbound fulfilment.
Tenant settings, address data, order lines, supplier identifiers, and other required fields are validated and mapped.
If Wayfair accepts the request, the queue reaches **Completed**, the fulfilment reference is stored, and Linnworks receives **Sent to WayfairCastleGate**. If validation fails, the queue becomes **ValidationFailed** and Linnworks receives an error identifier and note.
When Wayfair reports **SHIPPED** with tracking data, shipping information is updated and the fulfilment-centre order is processed in Linnworks.
If a supported cancellation is accepted before shipment, the cancellation state becomes **Cancelled**.
---
## Validation Errors and Common Causes
| Validation Error | Cause |
| --------------------------------------------- | ---------------------------------------------------------------------------------- |
| Installation authorisation fails | Linnworks token is empty, invalid, expired, or unregistered |
| Active installation exists with another token | A previous uninstall was not registered before reinstallation |
| No active integration found | Configuration is incomplete, inactive, or not linked to the installation |
| Multiple active integrations found | Duplicate active configurations exist for one installation |
| Supplier ID missing | The Wayfair Supplier ID was not saved |
| CastleGate 3PL location missing | The location was renamed, deleted, or not mapped during installation |
| Order has no items | The Linnworks order contains no usable order lines |
| Shipping address incomplete | Address line 1, town or city, postcode, or country is missing |
| Supplier part number missing | An item has no Channel SKU, Linnworks SKU, or Item Number |
| Shipping service mapping missing | No active mapping exists for the Linnworks postal service |
| Shipped order cannot process | Carrier, service, or tracking data is absent or incomplete |
| CastleGate inventory SKU skipped | Supplier part number does not exactly match a Linnworks SKU |
| Order already submitted | The order already carries the success identifier or an existing fulfilment linkage |
**Correct a Validation-Failed Order**
1. Open the Linnworks order carrying **`Error from WayfairCastleGate`**.
2. Read the internal Linnworks note and identify every validation error.
3. Correct the order, item, address, mapping, or integration configuration.
4. Remove **`Error from WayfairCastleGate`** only after all corrections are complete.
5. Allow the next fetch cycle to reload the order, or use an authorised manual action.
6. Confirm that the queue reaches **Completed**, a Wayfair fulfilment reference is present, and Linnworks carries **`Sent to WayfairCastleGate`**.
---
## Troubleshooting Guide
**Symptom:** Wayfair Dropship or CastleGate orders do not appear in Linnworks.
**Likely cause:** The installation is inactive, the subscription is suspended, the relevant order-sync feature is disabled, or Wayfair credentials or Supplier ID are missing.
**Resolution:** Verify installation and subscription state, confirm the relevant feature setting, and review inbound order and API audit logs.
**Symptom:** An eligible Linnworks order remains unsent.
**Likely cause:** 3PL order sync is disabled, multiple integrations are active, the order is not assigned to **CastleGate 3PL**, or required address or item data is missing.
**Resolution:** Confirm one active integration, enable 3PL order sync, verify the fulfilment location, and correct the order data.
**Symptom:** Linnworks carries **Error from WayfairCastleGate** and the order is excluded from automatic submission.
**Likely cause:** The order, item, address, mapping, or tenant configuration failed validation.
**Resolution:** Read the Linnworks internal note, correct every issue, remove the error identifier, and allow the order to be fetched again.
**Symptom:** A Wayfair fulfilment is shipped but the Linnworks order remains open or lacks tracking details.
**Likely cause:** Dispatch sync is disabled, Wayfair has not reported **SHIPPED**, or carrier or tracking data is incomplete.
**Resolution:** Confirm dispatch sync, inspect the Wayfair status, and review the queue error, API log, and correlation ID.
**Symptom:** CastleGate fulfilment stock does not match the **CastleGate 3PL** Linnworks location.
**Likely cause:** The location was renamed or unmapped, the SKU does not match exactly, or the inventory job is disabled or failed.
**Resolution:** Restore the location mapping, correct the SKU relationship, confirm scheduling, and review inventory audit counts and errors.
**Symptom:** A user cannot access the integration portal.
**Likely cause:** The wrong email is being used, the user or installation is inactive, or the temporary password has expired or been lost.
**Resolution:** Use the Linnworks installation email, verify account activity, and ask an administrator to issue a password reset.
---
## Deliverables
Automated inbound order, outbound fulfilment, cancellation, shipment, product, and stock workflows between Linnworks and Wayfair.
Linnworks authorisation, tenant configuration, Wayfair credentials, feature controls, environment selection, and subscription management.
Controlled mapping between Linnworks postal services and Wayfair carrier SCAC and ship-speed values.
Operational views for queues, configuration, products, inventory, fulfilment, cancellations, diagnostics, API history, and supported retries.
Timestamped audit records, payload history, queue state, errors, and correlation IDs for end-to-end investigation.
Tenant-aware scheduled jobs for order import, fulfilment submission, cancellation, shipment processing, catalogue retrieval, inventory synchronisation, verification, and subscription checks.
---
## Best Practices
> Consistent configuration, exact identifiers, and regular monitoring are essential for a reliable Wayfair and CastleGate integration.
Validate order import, product retrieval, inventory submission, 3PL fulfilment, cancellation, shipment processing, identifiers, and service mappings before using Production.
Restrict portal access, rotate secrets through the approved process, and never place Client Secrets, tokens, or passwords in order notes or support tickets.
Use consistent supplier part numbers across Linnworks and Wayfair. CastleGate inventory matching requires an exact Linnworks SKU.
Review mappings whenever postal services, carriers, or shipping options change, and keep only intended mappings active.
Treat **Sent to WayfairCastleGate** as the success marker and **Error from WayfairCastleGate** as a correction-required marker. Remove the error marker only after correcting the order.
Provide order references, queue status, UTC timestamp, exact error text, and correlation ID so support can trace the workflow quickly.
---
## FAQ
**Is the integration fully automatic?**
Yes, after installation, configuration, service mapping, and scheduler setup. Manual intervention is still required for validation errors, unsupported data, expired credentials, suspended subscriptions, or exhausted retry limits.
**Which orders are sent from Linnworks to Wayfair fulfilment?**
The outbound 3PL job reads eligible open orders from the mapped **CastleGate 3PL** fulfilment location when **Enable 3PL Order Sync** is active.
**How do I retry a validation-failed 3PL order?**
Read the Linnworks internal note, correct the order, remove **Error from WayfairCastleGate**, and wait for the next fetch cycle or use an authorised manual action.
**Why does an order have Sent to WayfairCastleGate?**
The identifier means Wayfair accepted the outbound fulfilment request. It prevents the order from being treated as a new, unsent order during normal processing.
**Why is a shipped order still open in Linnworks?**
Check that dispatch sync is enabled, Wayfair reports **SHIPPED**, and carrier and tracking data are present. Missing tracking data prevents the Linnworks fulfilment-centre processing step.
**Can I cancel an order after it has been submitted to Wayfair?**
Yes, if cancellation sync is enabled and Wayfair still considers the order cancellable. If Wayfair reports **NotCancellable** or the order is already shipped, normal shipment processing applies.
**Can the integration update Wayfair prices?**
No. The current implementation rejects direct product price updates because the supported product update flow does not provide a catalogue price field.
**Does Sandbox change live Wayfair inventory?**
No. Sandbox inventory submissions use dry-run behaviour. Use Sandbox to validate payloads and workflow without relying on a live stock change.
**Can the same integration support multiple Linnworks accounts?**
Yes. Each Linnworks installation is handled as an independent tenant with separate credentials, settings, queues, mappings, audit data, and portal access.
**What happens when the subscription is suspended?**
Protected workflows stop for that installation. A subscription-based suspension can be restored automatically after the scheduled check confirms that the Linnworks application profile is active. An administrator must change an admin-controlled suspension.
**I installed the app but cannot see it in Linnworks. What should I do?**
Open **Apps > My Applications**, refresh the page, or sign out and back in. If the app is still missing, confirm that the authorised Linnworks installation flow completed successfully.
**I cannot sign in to the Wayfair & CastleGate Integration portal. What should I do?**
Use the email address associated with the Linnworks installation and the portal password supplied or reset for that account. Portal credentials are separate from Wayfair and Linnworks credentials. Contact an administrator if a password reset is required.
---
## Legal Information
- **Privacy Policy:** [https://rishvi.co.uk/privacy-policy/](https://rishvi.co.uk/privacy-policy/)
- **Terms and Conditions:** [https://rishvi.co.uk/terms-conditions/](https://rishvi.co.uk/terms-conditions/)
Please review these pages to understand how data is handled and the terms governing use of the integration.
---
## Summary
The Linnworks ↔ Wayfair & CastleGate Integration, powered by Rishvi Services, provides a structured and auditable connection between Linnworks and the Wayfair ecosystem.
Wayfair and CastleGate orders can flow into Linnworks, while eligible Linnworks orders are validated and submitted to Wayfair Multi-Channel Fulfilment.
Shipped fulfilments update Linnworks with carrier, service, and tracking data before the fulfilment-centre order is processed.
Linnworks stock changes can be submitted to Wayfair, while CastleGate fulfilment stock updates the dedicated Linnworks location.
Multiple Linnworks installations are supported with independent credentials, environments, mappings, feature controls, queues, and audit data.
Durable queues, validation, deduplication, controlled retries, subscription checks, audit logs, and correlation IDs support reliable processing.
Operational teams can review configuration, failures, fulfilment states, inventory results, API history, and supported recovery actions.
For issues that cannot be resolved automatically, the support portal provides the error details, correlation IDs, queue state, and controlled actions needed to diagnose and correct the problem.