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
Linnworks
Acts as the operational system for orders, products, postal services, stock locations, identifiers, and fulfilment processing.
Rishvi Services
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.
Wayfair & CastleGate
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.
Order Fulfilment
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.
Stock Synchronisation
Sends eligible Linnworks inventory changes to Wayfair and updates the mapped CastleGate 3PL Linnworks location with fulfilment stock returned by CastleGate.
Shipment Tracking Updates
Checks Wayfair fulfilment status, writes carrier and tracking information to Linnworks, and processes shipped fulfilment-centre orders when the required shipment data is available.
Tenant Configuration Management
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
- Sign in to your Linnworks account.
- Select Settings from the left-hand navigation menu.
- Under Settings, select Channel integration.
- On the Channel Integrations page, click Add New.
The Add Channel window opens.
Install the Wayfair CastleGate application
- Search for WAYFAIR CASTLEGATE.
- Confirm that the application is provided by Rishvi Ltd.
- Review the application information and documentation if required.
- 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.
- Enter a descriptive name in Account Name.
- Use a name that distinguishes this account from other Wayfair integrations.
- Click Next.
The account name becomes the channel's subsource name on the Channel Integrations page.
Review and accept the disclaimer
- Read the third-party application disclaimer.
- Review the linked terms and conditions.
- Select I agree to the terms and conditions.
- Click Next.
You must accept the terms and conditions before continuing.
Select the integration profile
-
Open the Integration Profile dropdown.
-
Select:
Common Integration - Basic order and inventory sync
-
Confirm that the correct profile is displayed.
-
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:
- Confirm that the credentials and Supplier ID are correct.
- Confirm that the correct Wayfair environment is selected.
- Enable the required synchronisation options.
- 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:
- Confirm that the integration has been completed.
- 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.
Step 1 - Tenant configuration validation
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.
Step 2 - Order data mapping
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
Step 3 - Order submission to Wayfair
Valid orders are submitted to Wayfair Multi-Channel Fulfilment. The integration records the Wayfair fulfilment request identifier, request result, processing state, and audit details.
Step 4 - Order linkage stored
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.
Step 5 - Linnworks order updated
After Wayfair accepts the request, the integration assigns ``` to the Linnworks order. If validation fails, it assigns `` 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.
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:
- Retrieves CastleGate inventory-summary pages.
- Adds fulfillable quantities across CastleGate warehouses for each supplier part number.
- Matches the supplier part number to a Linnworks SKU exactly.
- Writes matching quantities to the CastleGate 3PL Linnworks location in batches of up to 50.
- 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
Support Multiple Customers
One integration platform can serve multiple Linnworks installations without mixing orders, credentials, queues, or audit records.
Support Multiple Environments
Each tenant can be configured independently for Wayfair Sandbox or Production.
Independent Feature Control
Order import, fulfilment, cancellation, and dispatch synchronisation can be enabled or disabled per tenant.
Isolated Credentials
Linnworks and Wayfair credentials and operational data are scoped to the relevant tenant and portal permissions.
Production-Readiness Features
Durable Queues
Inbound orders, fulfilment orders, operations, cancellations, and synchronisation results are persisted so processing state survives beyond one request.
Controlled Retry Handling
Failed operations retain their retry count and error details. Eligible technical failures can be processed again within configured limits.
Fail-Fast Configuration Validation
Required settings and order data are checked before submission. Validation failures are written to Linnworks and surfaced in the portal for correction.
Deduplication
Wayfair order references, CastleGate purchase-order numbers, fulfilment references, and Linnworks identifiers prevent normal scheduler cycles from creating duplicate records.
Correlation IDs
Correlation IDs connect queue history, audit entries, and API logs so a transaction can be traced across systems.
Subscription Gating
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
Manage Tenant Setup
Review installation state, integration configuration, Wayfair environment, feature settings, and subscription state.
Configure Shipping Mappings
Map Linnworks postal services to the required Wayfair carrier SCAC and ship-speed values.
View Diagnostics
Search inbound queues, outbound fulfilment queues, cancellations, product operations, stock-sync audits, API logs, and correlation IDs.
Review Failed Events
Inspect validation errors, failed operations, retry counts, payload history, and exact failure messages.
Retry Failed Processes
Authorised users can trigger supported fetch, send, retry, or synchronisation actions after the underlying issue is corrected.
Audit Trail
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
Pending
An eligible Linnworks order assigned to CastleGate 3PL is identified and queued for outbound fulfilment.
Validating
Tenant settings, address data, order lines, supplier identifiers, and other required fields are validated and mapped.
Completed or ValidationFailed
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.
ProcessedInLinnworks
When Wayfair reports SHIPPED with tracking data, shipping information is updated and the fulfilment-centre order is processed in Linnworks.
Cancelled (if applicable)
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
- Open the Linnworks order carrying ```.
- Read the internal Linnworks note and identify every validation error.
- Correct the order, item, address, mapping, or integration configuration.
- Remove ``` only after all corrections are complete.
- Allow the next fetch cycle to reload the order, or use an authorised manual action.
- Confirm that the queue reaches Completed, a Wayfair fulfilment reference is present, and Linnworks carries ```.
Troubleshooting Guide
Orders are not importing
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.
3PL orders are not sending
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.
Order shows ValidationFailed
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.
Shipment tracking not updating in Linnworks
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.
Stock levels are out of sync
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.
Login or password problem
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
Production-Ready Integration Service
Automated inbound order, outbound fulfilment, cancellation, shipment, product, and stock workflows between Linnworks and Wayfair.
Installation and Configuration Portal
Linnworks authorisation, tenant configuration, Wayfair credentials, feature controls, environment selection, and subscription management.
Shipping Service Mappings
Controlled mapping between Linnworks postal services and Wayfair carrier SCAC and ship-speed values.
Support Portal
Operational views for queues, configuration, products, inventory, fulfilment, cancellations, diagnostics, API history, and supported retries.
Audit and API History
Timestamped audit records, payload history, queue state, errors, and correlation IDs for end-to-end investigation.
Scheduled Automation
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.
Test in Sandbox first
Validate order import, product retrieval, inventory submission, 3PL fulfilment, cancellation, shipment processing, identifiers, and service mappings before using Production.
Protect credentials
Restrict portal access, rotate secrets through the approved process, and never place Client Secrets, tokens, or passwords in order notes or support tickets.
Keep SKUs consistent across systems
Use consistent supplier part numbers across Linnworks and Wayfair. CastleGate inventory matching requires an exact Linnworks SKU.
Maintain shipping service mappings
Review mappings whenever postal services, carriers, or shipping options change, and keep only intended mappings active.
Use order identifiers correctly
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.
Use correlation IDs for investigation
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/
- Terms and 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.
Automated order fulfilment
Wayfair and CastleGate orders can flow into Linnworks, while eligible Linnworks orders are validated and submitted to Wayfair Multi-Channel Fulfilment.
Shipment tracking updates
Shipped fulfilments update Linnworks with carrier, service, and tracking data before the fulfilment-centre order is processed.
Reliable stock synchronisation
Linnworks stock changes can be submitted to Wayfair, while CastleGate fulfilment stock updates the dedicated Linnworks location.
Multi-tenant support
Multiple Linnworks installations are supported with independent credentials, environments, mappings, feature controls, queues, and audit data.
Production-ready reliability
Durable queues, validation, deduplication, controlled retries, subscription checks, audit logs, and correlation IDs support reliable processing.
Support portal visibility
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.