ShipStation Integration¶

Overview¶

The ShipStation Integration module connects Odoo 18 with the ShipStation shipping platform using the ShipStation API v2. It supports two primary fulfillment workflows:

Label Workflow -- Generate shipping labels directly from Odoo through the ShipStation API, with rates, tracking numbers, and label PDFs returned inline.
Export Workflow -- Push orders from Odoo into ShipStation as pending shipments, then receive tracking numbers back automatically via webhooks when staff ship from ShipStation.

The module also provides carrier/service syncing, warehouse mapping, inventory push, product catalog sync, batch label generation, return labels, pickup scheduling, and end-of-day manifests.


Module	`shipstation`
Version	18.0.1.1.0
Category	Inventory / Delivery
License	LGPL-3
Author	Longhorn Web Solutions

Installation & Dependencies¶

Odoo Module Dependencies¶

Module	Purpose
`base`	Core framework
`sale`	Sale order integration
`stock`	Warehouse and picking operations
`delivery`	Delivery carrier framework
`stock_delivery`	Stock-delivery bridge
`mail`	Chatter logging and notifications
`product_addons`	Extended product fields (dimensions, MSRP)

Python Dependencies¶

Package	Purpose
`requests`	HTTP client for ShipStation REST API calls

Installation Steps¶

Copy the shipstation folder into your Odoo custom addons directory.
Navigate to Settings > Apps > Update Apps List.
Search for ShipStation Integration and click Install.

Instance Configuration¶

A ShipStation Instance is the central configuration hub. Each instance represents one ShipStation account and stores API credentials, sync settings, and webhook configuration. The module supports multiple instances for multi-account setups.

Creating an Instance¶

Navigate to Inventory > ShipStation > Instances.
Click New and fill in:

Field	Description
Name	A friendly name for this ShipStation account
Company	The Odoo company this instance belongs to
API Key	Your ShipStation API v2 key
API URL	The ShipStation API base URL (default: `https://api.shipstation.com`)

Settings¶

Setting	Description
Weight UoM	Unit of measure for weights sent to ShipStation: Pounds, Ounces, or Grams
Dimension UoM	Unit of measure for package dimensions: Inches or Centimeters
Debug Mode	When enabled, logs full API request/response payloads (disable in production)
Auto-Export on Ready	Automatically export pickings to ShipStation when they reach the "Ready" state
Auto-Validate on Ship	Automatically validate pickings in Odoo when ShipStation reports them as shipped via webhook

Testing the Connection¶

Click the Test Connection button on the instance form. A successful test returns the number of carriers found in your ShipStation account.

API Key Location

You can find your ShipStation API key under Settings > API Keys in your ShipStation dashboard at ss.shipstation.com.

Delivery Method Setup¶

ShipStation shipping methods are configured as Odoo Delivery Carriers with the provider set to "ShipStation".

Creating a Delivery Method¶

Navigate to Inventory > Configuration > Delivery Methods.
Click New and set Provider to ShipStation.
Configure the ShipStation-specific fields:

Field	Description
ShipStation Instance	Select the instance to use for API calls
ShipStation Carrier	The carrier account (UPS, FedEx, USPS, etc.) synced from ShipStation
ShipStation Service	The specific service level (e.g., UPS Ground, FedEx Home Delivery)
Default Package Type	The default package type for this delivery method
Workflow	Label (generate labels from Odoo) or Export (push orders to ShipStation)

Additional Label Options¶

Option	Description
Confirmation	None, Delivery Confirmation, Signature Required, Adult Signature, or Direct Signature
Label Format	PDF, PNG, or ZPL
Label Layout	4x6 or Letter

Order Synchronization¶

Export Workflow¶

The Export workflow pushes Odoo delivery orders (stock pickings) into ShipStation as pending shipments. Staff then process and ship these orders within the ShipStation web interface.

Manual Export:

Open a delivery order (stock picking) that uses a ShipStation delivery method with the Export workflow.
Click the Export to ShipStation button.
The picking's status updates to Exported and an external shipment ID is recorded for webhook matching.

Automatic Export:

When Auto-Export on Ready is enabled on the instance, pickings are automatically exported to ShipStation when they reach the "Ready" (assigned) state.

What Gets Exported¶

Each exported shipment includes:

Ship-to and ship-from addresses
Line items with SKU, quantity, unit price, and weight
Package weight and dimensions
Carrier and service codes (if configured on the delivery method)
Mapped ShipStation warehouse
Sale order amount (if linked)

US Address Requirements

Pickings with US destinations require a state and ZIP code on the shipping address before export. Missing address fields will cause an export error.

Label Generation¶

The Label workflow generates shipping labels directly through the ShipStation API without needing to interact with the ShipStation web interface.

How It Works¶

On a delivery order, click Validate (or use the standard "Send to Shipper" flow).
Odoo sends a rate request to ShipStation (POST /v2/rates) with the shipment details.
The best matching rate is selected based on the configured service.
Odoo purchases the label using the rate ID (POST /v2/labels/rates/{rate_id}).
The tracking number and label file are attached to the picking's chatter.

Label Formats¶

Format	Description
PDF	Standard printable label
PNG	Image format label
ZPL	Zebra Programming Language for thermal printers

Voiding Labels¶

To void a generated label, use the Cancel Shipment action on the delivery order. This calls the ShipStation void endpoint and clears the label and shipment IDs from the picking.

Tracking Number Imports¶

Tracking numbers flow back into Odoo automatically through webhooks when using the Export workflow.

Webhook-Based Tracking¶

When a shipment is fulfilled in ShipStation, the fulfillment_shipped_v2 webhook fires and updates the Odoo picking with:

Tracking number (appended if multiple shipments)
Carrier and service codes
Ship date
Shipping cost
Export status set to Shipped

Auto-Validation¶

When Auto-Validate on Ship is enabled on the instance, the webhook handler also:

Sets the done quantities on all move lines
Calls button_validate() on the picking
Marks the picking as Done in Odoo

Tracking Links¶

The module provides carrier-specific tracking URLs for the following carriers:

Carrier	Tracking URL
UPS	ups.com/track
FedEx	fedex.com/fedextrack
USPS	tools.usps.com tracking
DHL Express	dhl.com tracking
Stamps.com	USPS tracking (same as USPS)

For unrecognized carriers, a Google search fallback is used.

Carrier & Service Management¶

Carriers, services, and package types are synced from your ShipStation account and stored locally in Odoo.

Syncing Carriers¶

Open your ShipStation instance.
Click Sync All (or Sync Carriers individually).
The module fetches all carrier accounts from the ShipStation API and creates or updates local records.

Data Model¶

Model	Description
ShipStation Carrier	Carrier accounts (e.g., UPS, FedEx, USPS) with account numbers and balance info
Carrier Service	Shipping services per carrier (e.g., UPS Ground, FedEx 2Day) with domestic/international flags
Carrier Package	Package types per carrier with dimensions (e.g., FedEx Envelope, USPS Flat Rate Box)

Soft Delete¶

Carriers, services, and packages that no longer exist in ShipStation are deactivated (soft deleted) rather than removed, preserving historical data on existing pickings.

Warehouse Mapping¶

ShipStation warehouses are synced and can be mapped to Odoo warehouses for correct ship-from address routing.

Syncing Warehouses¶

Open your ShipStation instance.
Click Sync All (or Sync Warehouses individually).
Warehouses are created with address details from ShipStation.

Mapping to Odoo¶

On each synced ShipStation warehouse record, set the Odoo Warehouse field to link it to a stock.warehouse record. When exporting orders, the module uses this mapping to set the correct ShipStation warehouse ID on the shipment.

Webhook Setup¶

Webhooks allow ShipStation to push real-time updates (tracking numbers, shipment status) back to Odoo.

Registering Webhooks¶

Open your ShipStation instance.
Click Register Webhooks.
The module automatically:
- Generates a webhook secret (if not already set)
- Registers fulfillment_shipped_v2 and shipment_created_v2 events with ShipStation

Webhook URL¶

The webhook endpoint is:

https://your-odoo-domain.com/shipstation/webhook/{instance_id}

This URL is displayed on the instance form and is automatically passed to ShipStation during registration.

Security¶

Webhooks are secured using a secret token:

A unique X-Odoo-Secret header is sent with each webhook registration.
Incoming webhook requests are verified against this secret.
Requests with missing or invalid secrets are rejected.

Supported Events¶

Event	Handler
`fulfillment_shipped_v2`	Updates picking with tracking number, carrier info, and optionally auto-validates
`shipment_created_v2`	Logged for reference
`label_created_v2`	Logged for reference
`track_event_v2`	Logged for reference
`SHIP_NOTIFY` (v1 legacy)	Fetches shipment details and updates pickings
`ORDER_NOTIFY` (v1 legacy)	Logged only

Public Endpoint

The webhook endpoint uses auth='none' because ShipStation cannot authenticate with Odoo session cookies. Security is enforced through the webhook secret header verification.

Product & Inventory Sync¶

Product Sync¶

Enable Product Sync on the instance to synchronize products between Odoo and ShipStation.

Pull Products (ShipStation to Odoo):

Click Sync Products on the instance to import all products from ShipStation.
Products are matched by SKU and auto-linked to existing Odoo products.

Push Products (Odoo to ShipStation):

Click Push Products to export Odoo products (with SKU and saleable) to ShipStation.
Product data includes name, SKU, price, cost, weight, dimensions, and barcode.

Auto-Link by SKU:

Click Auto-Link Products to match ShipStation products to Odoo products based on matching SKU/Internal Reference.

Inventory Sync¶

Enable Inventory Sync on the instance to push Odoo stock levels to ShipStation.

Set a Default SS Warehouse for inventory sync.
Click Push Inventory to send current qty_available for all stocked products with an internal reference.
Sync records track the last synced quantity, date, and any errors per product/warehouse combination.

Batch Labels & Advanced Features¶

Batch Label Generation¶

Create batches to process multiple shipment labels at once:

Navigate to Inventory > ShipStation > Batches.
Create a new batch, add exported pickings, and select label format/layout.
Click Create Batch to register the batch in ShipStation.
Click Process Batch to queue label generation.
Use Refresh Status to check progress and get the label download URL.

Return Labels¶

Generate return shipping labels from previously exported shipments:

Create a return label record linked to the original picking.
Optionally enter an RMA number.
Click Create Return Label to generate the label via ShipStation API.

Pickup Scheduling¶

Schedule carrier pickups from your warehouse:

Navigate to Inventory > ShipStation > Pickups.
Select the carrier, warehouse, date, and time window.
Click Schedule Pickup to register with the carrier.

End-of-Day Manifests¶

Generate SCAN forms (end-of-day manifests) for carrier compliance:

Navigate to Inventory > ShipStation > Manifests.
Select the carrier, warehouse, and ship date.
Click Create Manifest to generate and download the manifest.

Multi-Account Support¶

The module fully supports multiple ShipStation accounts:

Each Instance represents a separate ShipStation account with its own API credentials.
All data models (carriers, warehouses, products, webhooks, logs) are scoped by instance_id.
Company-level isolation: Record rules enforce company_id filtering across all models.
Different delivery methods can point to different instances.
The Settings page allows selecting a default instance per company.

Security¶

Access Groups¶

Group	Permissions
ShipStation / User	Read-only access to all ShipStation records
ShipStation / Manager	Full create, read, update, delete access

Multi-Company Rules¶

All ShipStation models include a company_id field with record rules enforcing [('company_id', 'in', company_ids)], ensuring data isolation between companies.

Troubleshooting¶

Connection Issues¶

Connection Failed

Symptom: "Connection failed" error when testing the connection.

Resolution:

Verify your API key is correct and active in ShipStation.
Confirm the API URL is https://api.shipstation.com.
Check that your server can reach the ShipStation API (no firewall or proxy blocks).

Export Errors¶

Missing Address Fields

Symptom: Export fails with "Ship-to address is missing" errors.

Resolution:

Ensure the delivery address has Street, City, and Country filled in.
For US addresses, State and ZIP code are required.
Verify the warehouse partner (ship-from) has a ZIP code and Country.

Webhook Not Firing¶

Tracking Numbers Not Importing

Symptom: Orders shipped in ShipStation but tracking numbers do not appear in Odoo.

Resolution:

Verify webhooks are registered: check the Webhooks tab on the instance.
Ensure your Odoo instance is publicly accessible (ShipStation must be able to reach the webhook URL).
Check the webhook URL matches your public domain.
Review ShipStation Logs for any webhook errors.
If using a reverse proxy, ensure POST requests to /shipstation/webhook/* are forwarded correctly.

Rate Errors¶

No Rates Returned

Symptom: "No rates returned from ShipStation" when validating a delivery order.

Resolution:

Verify the carrier and service are correctly configured on the delivery method.
Ensure product weights are set (the module defaults to 1 lb if total weight is zero).
Check that addresses are complete and valid.
Review ShipStation logs with Debug Mode enabled for the full API response.

Debug Logging¶

Enable Debug Mode on the instance to log full API request and response payloads. Logs can be viewed at Inventory > ShipStation > Logs and are filterable by operation type, status, and related picking.

Disable Debug Mode in Production

Debug mode logs contain sensitive data (addresses, API payloads). Disable it after troubleshooting to avoid excessive log storage.