ShipStation ↔ NetSuite Integration (SuperSync)
This document describes how the legacy ShipStation connector behaves and what each configuration field means. Use this as a reference when setting up, troubleshooting, or understanding how your ShipStation integration is configured in SuperSync.
Overview
SuperSync connects ShipStation with NetSuite to keep orders, fulfillments, and shipment data in sync between the two platforms. Depending on how your flow and mapping are configured, data can move in one or both directions.
| Direction | Typical Use |
|---|
| ShipStation → NetSuite | Import orders, fulfillments, shipments, or return authorisations from ShipStation into NetSuite |
| NetSuite → ShipStation | Push sales orders from NetSuite into ShipStation for fulfillment |
Authentication uses Basic Auth with a ShipStation API Key and API Secret. All requests are made to https://ssapi.shipstation.com.
Credentials
| Field | Required | Description |
|---|
API_KEY | Yes | Your ShipStation API Key. Found in ShipStation under Settings > API Settings. |
API_SECRET | Yes | Your ShipStation API Secret. Found alongside the API Key in ShipStation settings. Missing either value will prevent the integration from initialising. |
ShipStation → NetSuite
This direction pulls records from ShipStation and creates or updates the corresponding records in NetSuite.
Supported Record Types
Set the Record Type field in your flow mapping to one of the following values:
| Record Type Value | What It Syncs |
|---|
order or salesorder | ShipStation orders → NetSuite sales orders |
itemfulfillment, fulfillment, or shipment | ShipStation fulfillments/shipments → NetSuite item fulfillments |
returnauthorisation | ShipStation return shipments (where isReturnLabel is true) → NetSuite |
employee | ShipStation users → NetSuite employees |
How Incremental Sync Works
For orders and fulfillments, SuperSync uses the last successful sync date as the start of the next sync window, with a floor set by the Live Date config. This ensures only new or updated records are pulled on each run.
Configuration Fields
Identity and Date Fields
These fields tell SuperSync which properties on the ShipStation record to use for tracking, deduplication, and date windowing.
| Field | Default (orders) | Default (fulfillments) | Description |
|---|
ID | orderId | fulfillmentId | The ShipStation field used as the unique record identifier. Used for deduplication — records with a matching ID that have already synced successfully will be skipped. |
REFERENCE | orderNumber | orderNumber | The ShipStation field stored as the transaction reference in SuperSync. |
DATE | modifyDate | modifyDate | The ShipStation date field used to drive the sync window. Must be a valid date property on the ShipStation record. |
LIVE_DATE | 2021-12-25 | 2021-12-25 | The earliest date from which records will be synced. Records before this date are ignored. Also acts as the floor for incremental sync. Format: YYYY-MM-DD. |
Order-Specific Fields
| Field | Description |
|---|
STATUSES | A comma-separated list of ShipStation order statuses to filter by (e.g. awaiting_shipment,on_hold). When set, SuperSync runs a separate API call for each status and merges the results. If left empty, all statuses are returned. Note: ShipStation's API only supports one status filter per request — SuperSync handles the iteration automatically. |
Fulfillment-Specific Fields
| Field | Default | Description |
|---|
SEARCH_MAPPING_NAME | (empty) | When set, SuperSync uses a NetSuite saved search (identified by this name) to retrieve a list of order IDs, then fetches each fulfillment from ShipStation individually. When left empty, SuperSync fetches fulfillments using a time-based window instead. |
NS_ORDER_ID_PROPERTY | internalid | Required when SEARCH_MAPPING_NAME is set. Specifies which field in the NetSuite search results contains the order ID to look up in ShipStation. |
ORDER_IDENTIFIER | OrderId | The ShipStation field used to match fulfillments to orders when fetching by order. Defaults to OrderId. |
LOOKUP_ORDER | false | When set to true, SuperSync performs an additional ShipStation API call to retrieve the originating order for each fulfillment and attaches it to the record before mapping. Useful when the mapping requires order-level fields not present on the fulfillment. |
Write-Back Fields (ShipStation → NetSuite)
After a record is successfully synced to NetSuite, SuperSync can optionally write an export status back to the original NetSuite record.
| Field | Default | Description |
|---|
MARK_IN_NETSUITE | custbody_ss_exported_id | The NetSuite custom field where the ShipStation result ID is written after a successful sync. |
MARK_IN_NETSUITE_EXPORTED_SUCCESS | custbody_ss_export_success | The NetSuite custom field used to flag a record as successfully exported. |
Mapping Configuration
The Mapping Configuration JSON defines how each ShipStation record is transformed into a NetSuite record. This is not a ShipStation API setting — it is input to SuperSync's decoder and controls what NetSuite receives (field values, nesting, line items, date formatting, etc.).
- Changing ID, DATE, or REFERENCE affects which ShipStation fields are used for tracking and deduplication — it does not affect the NetSuite payload directly.
- Changing the Mapping Configuration JSON controls what data is written to NetSuite.
NetSuite → ShipStation
This direction reads records from NetSuite using a saved search and pushes them to ShipStation as orders.
Supported Record Types
| Record Type Value | What It Syncs |
|---|
order or salesorder | NetSuite sales orders → ShipStation orders |
How It Works
- SuperSync runs the saved search defined in Search Mapping Name to retrieve a list of NetSuite records.
- Results are grouped by
internalid and compiled into order-level records with line items. - Each order is decoded using the Mapping Configuration JSON and sent to ShipStation.
- For order syncs, SuperSync batches records in groups of 5 for efficiency.
Configuration Fields
Identity and Date Fields
| Field | Default | Description |
|---|
ID | internalid | The NetSuite field used as the unique record identifier for deduplication and tracking. |
REFERENCE | tranid | The NetSuite field stored as the transaction reference in SuperSync. |
DATE | trandate | The NetSuite date field used for record validation. Must be present on each record. |
Search and Grouping Fields
| Field | Default | Description |
|---|
SEARCH_MAPPING_NAME | (required) | The name of a saved Flow Mapping that defines the NetSuite search used to retrieve records. Must match an existing mapping on the same account exactly. If missing or not found, the sync will throw an error. |
GROUP_RECORDS_BY | internalid | The field used to group NetSuite search result rows into single order records before sending to ShipStation. |
LINE_ITEM_PROPERTY | lineuniquekey | The field used to uniquely identify each line item row within a grouped record. |
LINE_ITEM_PROPERTIES | (list) | The set of fields carried over from NetSuite search results onto each line item. Defaults include sku, quantity, UnitPrice, description, location, and others. Can be inferred automatically from the Mapping Configuration JSON. |
MAINLINE_PROPERTY | mainline | The field used to identify the mainline row in a NetSuite search result. |
MAINLINE_VALUE | * | The value of MAINLINE_PROPERTY that indicates a row is the mainline. |
MAINLINE_PROPERTIES | (list) | The set of fields carried over from the mainline row onto the order-level record. Defaults include address fields, shipping fields, entity, email, and totals. |
Batch Processing
| Field | Default | Description |
|---|
NO_BATCHES | false | When set to true, records are sent to ShipStation one at a time instead of in batches of 5. Useful for troubleshooting or when batch processing causes issues. This is the same as enabling Sync records one-by-one in the flow mapping UI. |
Write-Back Fields (NetSuite → ShipStation)
After a record is successfully sent to ShipStation, SuperSync can write the ShipStation result back to the original NetSuite record.
| Field | Default | Description |
|---|
MARK_IN_NETSUITE | custbody_ss_exported_id | The NetSuite custom field where the ShipStation Order ID is written after a successful sync. |
MARK_IN_NETSUITE_EXPORTED_SUCCESS | custbody_ss_export_success | The NetSuite custom field used to flag a record as successfully exported to ShipStation. |
Troubleshooting
| Symptom | Likely Cause |
|---|
| "api key or api secret not set" | API_KEY or API_SECRET is missing from the flow mapping configuration. |
| "No Search Mapping Provided" | A NetSuite → ShipStation flow (or fulfillment flow using search mode) is missing SEARCH_MAPPING_NAME. |
| "flow mapping 'X' not found" | The value in SEARCH_MAPPING_NAME doesn't match any existing flow mapping on the account — check for typos or confirm the mapping exists. |
| Record skipped, no error | The record was already successfully synced (matching transaction ID and flow found in sync history). This is by design to prevent duplicates. |
| 401 / authentication error | API_KEY or API_SECRET is incorrect. Verify values in ShipStation under Settings > API Settings. |
| 429 / rate limit error | SuperSync automatically detects this and waits for the rate limit window to reset before retrying. No action needed. |
| Missing fields on fulfillments | If order-level fields are needed but not available on the fulfillment record, enable LOOKUP_ORDER to fetch the originating order from ShipStation. |
If you have questions or run into issues not covered here, reach out to supersync@netgain.tech.
