💡 Introduction

What is a Shipment?

A Shipment represents the physical delivery of parcels from your warehouse to the recipient. It contains all the information needed for carrier processing, including recipient details, package specifications, tracking information, and delivery preferences. Each shipment is routed through Seven Senders' intelligent carrier network to ensure optimal delivery performance.

Key Capabilities

The Shipments API provides comprehensive functionality to:

Create shipments - Generate new shipments with recipient and package details
Manage carrier information - Specify carriers, services, and routing preferences
Track deliveries - Monitor shipment status with carrier tracking numbers and URLs
Handle returns - Process return shipments with dedicated return parcel support
Support pickup points- Enable alternative delivery locations for customer convenience
Manage customs data - Include necessary information for international shipments
Update shipment details - Modify shipment information before carrier handover

Shipment Components

A complete shipment includes:

Recipient Information - Name, address, contact details, and company information
Package Details - Weight, dimensions, and declared goods value
Carrier Selection - Carrier name, country, and service type (standard, express)
Tracking Data - Tracking codes, reference numbers, and carrier tracking URLs
Delivery Options - Pickup point selection, planned pickup datetime, local delivery preferences
Order Reference - Link to associated order for unified tracking
Warehouse Information - Origin warehouse and address details

Relationship with Orders

Shipments and Orders are closely connected in the Seven Senders platform:

A Shipment represents the physical delivery of products from an Order
One order can have multiple shipments (partial fulfillment, split shipments, returns)
Shipments reference their parent order via order_id for end-to-end tracking
Return shipments can be linked back to the original order for return processing

Shipment Types

The API supports different shipment types:

Outbound Shipments - Standard deliveries from warehouse to customer (return_parcel: false)
Return Shipments - Customer returns back to warehouse (return_parcel: true)
Pickup Point Deliveries - Alternative delivery to pickup locations (pickup_point_selected: true)
Local Deliveries - Same-day or local delivery service options (local_delivery: true)

Tracking and Visibility

Every shipment provides comprehensive tracking capabilities:

tracking_code - Unique carrier tracking number for parcel monitoring
carrier_tracking_url - Direct link to carrier's tracking page
reference_number - Your internal shipment reference
trackable - Indicates whether the shipment supports real-time tracking

Common Use Cases

E-commerce Fulfillment - Create shipments automatically when orders are ready to ship
Multi-Carrier Shipping - Route shipments across different carriers based on destination and service requirements
Returns Management - Process customer returns with return labels and tracking
International Shipping - Handle cross-border shipments with customs information
Warehouse Integration - Connect warehouse systems to Seven Senders for automated shipping
Customer Communication - Provide tracking information and delivery updates to customers

Getting Started

To begin using the Shipments API:

Authenticate using your Seven Senders API credentials
Create a shipment with POST /shipments, including recipient details and package information
Specify carrier preferences or let Seven Senders optimize carrier selection
Retrieve the tracking code and carrier tracking URL from the response
Use GET /shipments to search and filter shipments with flexible query parameters
Update shipment details if needed before carrier handover

This introduction provides context, explains the business value, and helps developers understand how to effectively use the Shipments API for their logistics operations.