Stream Tech Integration — Linnworks to Stream: End-User Guide

Overview

The Stream Tech Integration connects Linnworks, your order management system, with Stream, a logistics and delivery management platform. Once configured, the integration automates the entire shipment lifecycle — from picking up open orders in Linnworks, creating consignments in Stream, and writing tracking numbers back to Linnworks, through to receiving real-time delivery status updates via webhooks.

Key flows the integration manages:

• Open orders in Linnworks are fetched and stored in the integration queue automatically, every five minutes.

• Each queued order is submitted to Stream to create a delivery or collection consignment.

• Stream returns a consignment number, tracking number, and tracking URL, which are written back to the Linnworks order immediately.

• Shipping labels are generated on demand directly from Linnworks using the Stream tracking data.

• Webhook events from Stream update Linnworks orders when deliveries are planned, dispatched, or completed.

• Order identifiers in Linnworks (such as "Sent to Stream", run numbers, and sequence numbers) provide visible, at-a-glance status for warehouse and dispatch teams.

The integration runs in the background via a scheduled job processor. Most operations require no manual intervention once services and credentials are configured.

---

Who Should Use This Integration

Warehouse Teams

Teams responsible for picking and packing use the integration's Linnworks order identifiers — particularly "Sent to Stream" and run/sequence numbers — to know which orders have been accepted by Stream and what delivery run they belong to. Label printing is also handled through this integration.

Logistics and Dispatch Teams

Dispatch teams use run identifiers (RUN 01 through RUN 20), sequence identifiers (SEQ-01 through SEQ-20), and day identifiers (SUNDAY through SATURDAY) to coordinate vehicle loading and route management. These identifiers are applied automatically to Linnworks orders as Stream plans and assigns delivery runs.

Integration Administrators

Administrators configure the integration's API credentials, sender address, sync settings, and postal service mappings. They also monitor the scheduler dashboard to verify that nightly master data syncs, order fetch jobs, and webhook processing jobs are running successfully.

Support Teams

Support staff use the integration's audit logs and order queue views to diagnose why an order was not sent, why a tracking number is missing, or why a delivery status has not updated. The "Error from Stream" identifier on a Linnworks order is the primary signal that an order needs attention.

---

Key Features

• Automated order synchronisation — Open Linnworks orders matching the configured lookback window are fetched every five minutes and queued for dispatch to Stream.

• Delivery and collection shipment creation — Each order is submitted to Stream as either a delivery order or a collection order, depending on the postal service configuration.

• Shipping label generation — Labels are generated directly from Linnworks in four available formats, with one to five copies per package.

• Tracking number synchronisation — Consignment numbers, tracking numbers, and tracking URLs are written back to Linnworks immediately after successful order creation in Stream.

• Real-time delivery status updates — Webhook events from Stream trigger order notes in Linnworks when an order is delivered, partially delivered, collected, or partially collected.

• Planning event synchronisation — Stream planning events (open planning, lock planning, close planning) update order group information in Linnworks.

• Run, day, and sequence identifier tagging — Linnworks order identifiers are automatically applied to reflect Stream delivery run assignments.

• Master data synchronisation — Stream depots, delivery methods, and order identifiers are synced into Linnworks daily to keep postal service mappings and identifier lists current.

• Configurable batch processing — Batch sizes and retry limits are configurable to match operational volume and API constraints.

• Full audit logging — Every fetch, send, label generation, and webhook event is logged with timestamps, correlation IDs, and outcome details.

• Order deletion with Stream cleanup — Completed orders can be deleted from Stream and cleared in Linnworks in a single operation.

---

Order Lifecycle

Every order that passes through the integration follows a defined progression of statuses. These statuses are visible in the integration's order queue view.

Lifecycle flow:

An order begins as Pending once fetched. The send job picks it up and moves it to In Progress. If Stream accepts it, the status moves to Completed. If Stream rejects it, the status moves to Failed, and the integration applies the "Error from Stream" identifier to the Linnworks order. On the next cycle, failed orders are moved to Ready for Retry and the send is attempted again, up to the configured maximum number of retry attempts (MaxRetryAttempts, default: 3). If all retries are exhausted, the order remains Failed until corrected. Orders with missing configuration move to Validation Failed and must be fixed before they can proceed. Once an order is Completed, it may later be moved to Deleted through a manual delete operation.

---

How Orders Are Sent to Stream

Eligibility

Before an order is submitted to Stream, the integration checks the following conditions:

• The installation must be active.

• The integration's Order Sync Enabled flag (IsOrderSyncEnabled) must be set to true. Manual sends bypass this check.

• The order must have a postal service assigned in Linnworks that is fully mapped to a Stream depot and delivery method.

• The order must not already be in In Progress status — concurrent sends of the same order are blocked.

If any condition is not met, the order is not sent and will not appear in the queue unless the issue is corrected.

Fetch Process

The scheduler runs a fetch job every five minutes for each active installation. This job:

1. Queries Linnworks for open orders within the configured lookback window (OrderLookbackDays, set per integration).

2. Stores any new orders in the integration's local order queue with status Pending.

3. Re-fetches orders that previously had a Validation Failed status to pick up any corrections made in Linnworks.

Page size for Linnworks order queries is configurable (OrderSyncPageSize, default: 50 per page).

Send Process

A send job runs every five minutes, staggered two minutes after the fetch job, for each installation. This offset ensures orders are fetched before the send cycle begins. The send job:

1. Reads up to MaxBatchSizePerInstallation (default: 5) Pending orders from the queue.

2. Locks each order as In Progress using optimistic concurrency — if another process has already claimed it, it is skipped.

3. Determines whether the order is a delivery or collection based on the postal service's Stream Order Type setting.

4. Transforms the Linnworks order data into a Stream delivery or collection request (see Shipment Creation and Label Generation).

5. Submits the request to the Stream API.

Up to MaxInstallationsPerBatch (default: 2) installations are processed simultaneously in each scheduler cycle.

On Success

When Stream accepts an order:

• The Stream order ID, consignment number, tracking number, and tracking URL are saved to the integration queue.

• The tracking number is written to the Linnworks order's shipping information.

• The "Sent to Stream" identifier is applied to the Linnworks order.

• The order queue status is set to Completed.

On Failure

When Stream rejects an order:

• The HTTP status code and error details are recorded in the order queue.

• The "Error from Stream" identifier is applied to the Linnworks order.

• The order status is set to Failed.

• On the next sync cycle, the order is automatically moved to Ready for Retry and re-submitted, up to MaxRetryAttempts (default: 3) times.

---

Shipping Service Setup

How Services Are Mapped

Each postal service in Linnworks that represents a Stream delivery option must be mapped to the corresponding Stream depot and delivery method. The mapping is stored per postal service and contains the following:

How Services Are Created

The integration performs a postal services master data sync daily at 4:00 AM. This sync:

• Fetches available depots and delivery methods from Stream.

• Creates or updates corresponding postal services in Linnworks under the STREAM TECH vendor name (or STREAMTECH in staging environments).

• Keeps the list of available services current as Stream's depot network changes.

Once a service appears in Linnworks, an administrator must complete its configuration by assigning the appropriate depot, delivery method, label type, and other settings before it can be used by orders.

Service Assignment

In Linnworks, assign the correct postal service to each order before the sync cycle runs. Orders without a valid, fully configured service will fail validation and will not be sent to Stream.

---

Shipment Creation and Label Generation

Shipment Creation

When the send job processes a Pending order, it builds a Stream shipment request using the following data from Linnworks:

• Order header — order reference, order date, customer details, and delivery address.

• Items — each order line item, with descriptions truncated to a maximum of 140 characters. Weights are submitted in kilograms and cubic volume in cubic metres.

• Composite items — by default, composite parent items are excluded from the Stream request; only child items are included. This is configurable per service via the Skip Composite Parent setting.

• Delivery group — the recipient's delivery address, any required contact information, and the configured delivery method.

The request is submitted as either a Delivery Order or a Collection Order based on the Stream Order Type configured on the postal service.

Label Generation

Labels are generated from within Linnworks using the standard shipping label print workflow. When Linnworks requests a label for an order:

1. The integration checks whether the order has been submitted to Stream and has a Completed status with a valid tracking number and consignment number.

2. If the order is not yet synced, the integration automatically fetches the order from Linnworks and submits it to Stream before generating the label.

3. If the order is currently In Progress (being submitted by a concurrent job), the integration waits up to approximately six seconds, polling every three seconds, before timing out.

4. If the sync fails, label generation is cancelled and an error is returned to Linnworks.

5. Once the order is confirmed as Completed, labels are generated for each package in the request.

Available label types:

The label type is configured per postal service. Each label is returned as a Base64-encoded PNG image and PDF document. The number of copies per package is configurable per service (1 to 5 copies).

Cancelling a label: Label cancellation requests from Linnworks always return a success response. No action is taken in Stream. This behaviour is required by the Linnworks integration contract.

---

Tracking Number and Shipment Updates

Tracking Written to Linnworks

Immediately after a successful shipment creation in Stream, the following are written to the Linnworks order:

• Tracking number — updated in the order's shipping information.

• Tracking URL — stored alongside the tracking number for reference.

• Consignment number — stored in the integration queue and used to match incoming webhook events.

Delivery Status Updates via Webhooks

If Webhook Features are enabled on the integration (IsWebhookFeaturesEnabled = true), the integration subscribes to Stream webhook events. These events are received, stored, and processed every two minutes by the webhook processing job.

The following delivery event codes trigger updates in Linnworks:

On receiving one of these events, the integration adds an order note to the corresponding Linnworks order with the delivery event details.

The following planning event codes trigger order group updates in Linnworks:

Mark as Processed on Delivered

When the Mark as Processed on Delivered option is enabled on a postal service, Linnworks orders on that service will automatically be marked as processed when Stream reports a DELIVERED or COLLECTED event. This removes the need for warehouse staff to manually mark orders as dispatched.

---

Run, Day, and Sequence Identifiers

Overview

The integration applies identifiers to Linnworks orders to reflect Stream's delivery route planning. These identifiers appear directly on the order in Linnworks and are the primary way warehouse and dispatch teams know which run, day, and sequence position an order belongs to.

All identifiers are registered in Linnworks via the master data sync that runs daily at 3:00 AM, ensuring the full set of identifiers is always available before the working day begins.

Run Identifiers

Run identifiers are applied to a Linnworks order when Stream assigns it to a specific delivery run during route planning. The identifier reflects the run number, making it straightforward for warehouse staff to sort and group orders before dispatch.

Sequence Identifiers

Sequence identifiers indicate the order's position within a run. They are applied alongside run identifiers. Sequence identifier support must be explicitly enabled by setting Group Sequence Identifier Enabled (IsGroupSequenceIdentifierEnabled = true) in the integration configuration. If not enabled, sequence identifiers will not be applied even when Stream provides sequence data.

Day Identifiers

Day identifiers reflect the scheduled delivery day as planned by Stream. They are applied to Linnworks orders via webhook events when Stream's route planning assigns a delivery date.

How Identifiers Are Applied

Identifiers are applied and removed automatically by the integration in response to Stream webhook events. Manual modification of these identifiers in Linnworks is not recommended, as the integration may overwrite or conflict with manually set values.

The maximum supported identifiers are: 20 run identifiers and 20 sequence identifiers.

---

Order Status Identifiers

The following identifiers appear on Linnworks orders and are managed by the integration. Each identifier serves as an at-a-glance status indicator.

---

Configuration Settings

Integration-Level Settings

These settings are configured per integration within the integration administration area. Each integration represents a Linnworks account connected to a Stream account.

---

Per-Service Settings

These settings are configured per postal service within the integration. They apply to every order dispatched using that service.

---

System-Level Settings

These settings are configured by administrators at the system level and apply across all installations.

---

Daily Operational Workflow

The following describes the typical day-to-day operational flow for teams using the integration.

1. Assign the correct postal service to orders in Linnworks. Before the sync cycle runs, each order must have a valid Stream postal service assigned. Orders without a service, or with a service that is not fully configured, will not be sent to Stream.

2. Wait for the scheduled fetch cycle. Every five minutes, the integration automatically retrieves open orders from Linnworks within the configured lookback window. No manual action is needed. Orders appear in the integration queue with status Pending.

3. Wait for the scheduled send cycle. Approximately two minutes after each fetch cycle, the send job processes Pending orders and submits them to Stream. Successfully submitted orders move to Completed status.

4. Confirm orders with the "Sent to Stream" identifier. Once submitted, the "Sent to Stream" identifier appears on the Linnworks order. This confirms the order has been accepted by Stream and has a tracking number.

5. Print shipping labels from Linnworks. Labels can be printed using the standard Linnworks shipping label workflow. The integration generates the label automatically using Stream tracking data. If the order has not yet been synced, the integration will attempt an immediate sync before generating the label.

6. Monitor for "Error from Stream" identifiers. Check for any orders tagged with the "Error from Stream" identifier. These orders require attention. Review the error message in the order queue, correct the underlying issue in Linnworks (for example, missing address or invalid service configuration), then trigger a re-fetch or wait for the next automatic sync cycle.

7. Watch for run, day, and sequence identifiers. As Stream plans delivery routes, run identifiers (RUN 01–RUN 20), day identifiers (MONDAY–SUNDAY), and sequence identifiers (SEQ-01–SEQ-20) are applied to orders automatically via webhooks. Use these to organise picking and loading by run and sequence.

8. Receive delivery confirmations in Linnworks. When Stream delivers an order, a delivery note is added to the corresponding Linnworks order automatically. If Mark as Processed on Delivered is enabled on the service, the Linnworks order is also marked as processed.

---

Validation Errors and Common Causes

The following errors can prevent an order from being submitted to Stream. Validation errors result in the order being moved to Validation Failed status. They will not be retried automatically until the underlying issue is resolved.

---

Troubleshooting Guide

---

Best Practices

• Configure postal services fully before orders arrive. Each service must have a Stream depot and delivery method mapped. Orders assigned to an incomplete service will fail and require manual re-processing.

• Keep Order Sync Enabled active. Setting IsOrderSyncEnabled = true on the integration ensures orders are submitted automatically without manual intervention. If disabled, orders must be triggered manually.

• Use a consistent order number prefix. The OrderNumPrefix setting applied to a Stream integration's order numbers should be unique and stable. Changing it mid-operation can cause reference mismatches in Stream.

• Do not manually modify identifier values in Linnworks. Identifiers such as "Sent to Stream", "RUN 01", and "SEQ-01" are managed by the integration. Manual changes may be overwritten on the next sync cycle.

• Monitor the "Error from Stream" identifier daily. This identifier is the primary signal that an order requires attention. Establish a daily check of orders carrying this identifier.

• Set an appropriate lookback window. The OrderLookbackDays setting controls how far back the fetch job retrieves orders. A value that is too short may miss orders processed on a previous day; a value that is too long may increase cycle time unnecessarily.

• Enable webhooks for live delivery tracking. Setting IsWebhookFeaturesEnabled = true enables real-time delivery event processing. Without webhooks, delivery status changes in Stream are not reflected in Linnworks.

• Enable sequence identifiers if using run-based dispatch. If your warehouse and dispatch team rely on sequence within a run for loading order, enable IsGroupSequenceIdentifierEnabled to apply SEQ-01 through SEQ-20 identifiers alongside run numbers.

• Keep batch sizes within safe limits. The default MaxBatchSizePerInstallation of 5 is conservative. Increasing it improves throughput but raises the risk of Stream API rate limiting. Adjust gradually and monitor for increased failure rates.

• Verify master data sync completes each night. The scheduler processes the identifier sync at 3:00 AM and the postal services sync at 4:00 AM. A failure in either sync can cause missing identifiers or outdated service mappings. Check the scheduler dashboard each morning.

---

FAQ

How often are orders automatically synced?

The fetch job runs every five minutes, retrieving open orders from Linnworks. The send job runs every five minutes, offset by two minutes, so orders are typically submitted to Stream within approximately seven minutes of being fetched.

What happens if Stream is temporarily unavailable?

If Stream is unavailable, order submissions will fail and be marked as Failed. The integration automatically retries failed orders on each subsequent cycle, up to MaxRetryAttempts times (default: 3). If Stream remains unavailable beyond the retry limit, orders will stay in Failed status until Stream is reachable and a manual or scheduled retry is triggered.

Can I manually trigger an order sync?

Yes. Individual orders or groups of orders can be manually selected and submitted through the integration's order management interface. Manual submissions bypass the IsOrderSyncEnabled check, so they will attempt to send even if the automated sync is disabled.

How do I fix an order with the "Error from Stream" identifier?

Open the integration order queue and locate the order. The queue view displays the last error message and HTTP status code returned by Stream. Correct the underlying issue — for example, a missing address field, an invalid delivery method, or an authentication problem — then wait for the next automatic retry cycle, or trigger a manual resend.

What is the difference between a delivery order and a collection order?

A delivery order instructs Stream to deliver goods to the recipient's address. A collection order instructs Stream to collect goods from an address. The order type is determined by the Stream Order Type setting on the postal service assigned to the Linnworks order. The default is Delivery.

How many orders can be submitted at once?

For the automated scheduler, up to MaxBatchSizePerInstallation orders (default: 5) are processed per installation per cycle. For manual bulk operations, users can select up to MaxUserSelectedOrders orders (default: 5) per operation.

What label types are available?

Four label types are supported:

• Default — 4×6 inch label with QR code and barcode.

• Portrait without QR — Portrait-oriented label without a QR code.

• Portrait Standard — Portrait-oriented standard label.

• Compact (100×50mm without QR) — Compact 100×50mm label without a QR code.

The label type is selected per postal service in the integration configuration.

Can I print multiple copies of a label?

Yes. The Label Copies setting on each postal service controls how many copies are printed per package. The supported range is 1 to 5 copies.

What does "Mark as Processed on Delivered" do?

When this setting is enabled on a postal service, Linnworks orders on that service are automatically marked as processed when Stream sends a delivery confirmation event (DELIVERED or COLLECTED). This removes the need for warehouse staff to mark the order manually after dispatch confirmation.

How do I enable run and sequence identifiers?

Run identifiers (RUN 01–RUN 20) are enabled automatically when webhook features are enabled (IsWebhookFeaturesEnabled = true) and Stream sends planning events for assigned orders. Sequence identifiers (SEQ-01–SEQ-20) additionally require IsGroupSequenceIdentifierEnabled = true in the integration configuration. Both sets of identifiers are pre-registered in Linnworks by the master data sync at 3:00 AM daily.

What happens if I try to delete a Pending or Failed order?

Only orders in Completed status can be deleted. Attempting to delete a Pending, Failed, or In Progress order will return an error. Resolve the order's status first — either wait for a successful send or correct any errors — before deleting.

Are webhook events retried if they fail to process?

Yes. If a webhook event fails to process, its retry count is incremented. It is moved to Ready for Retry status and reprocessed on the next webhook processing cycle (every two minutes). Events are retried up to WebhookMaxRetryAttempts times (default: 3). If all retry attempts are exhausted, the event is marked as Failed and will not be retried again automatically.

---

Summary

The Stream Tech Integration fully automates the order handoff between Linnworks and Stream. Once configured with valid Stream API credentials, sender address details, and properly mapped postal services, the integration runs continuously in the background:

• Orders are fetched from Linnworks every five minutes and submitted to Stream within a further two minutes.

• Tracking numbers and consignment IDs are written back to Linnworks immediately on success.

• Labels are generated on demand, with automatic sync triggered if an order has not yet been submitted.

• Webhook events from Stream apply run, day, and sequence identifiers to Linnworks orders in real time.

• Delivery confirmations can automatically mark Linnworks orders as processed.

• Master data syncs at 3:00 AM and 4:00 AM keep identifiers and postal services current.

The integration's order queue, audit logs, and scheduler dashboard provide full visibility into every sync operation, label generation event, and webhook activity. Administrators can adjust batch sizes, retry limits, and lookback windows to match operational volume and requirements.

For any order that cannot be automatically resolved, the "Error from Stream" identifier in Linnworks and the corresponding error detail in the order queue provide the information needed to diagnose and correct the issue.