Ship API Documentation

Environment	Base URL
Production	https://ship-api.com
Staging	https://staging.ship-api.com

Authorization: Bearer <your_api_token>

Retrieve shipping rates for a shipment. This endpoint calculates available shipping options and their costs based on the provided shipment details.

Request Body

The request body must contain a shipment object with the following structure:

Shipment Object

Field	Type	Description
ship_dateRequired	string	The scheduled shipping date and time in format YYYY-MM-DD HH:mm:ss
order_numberRequired	string	Unique identifier for the order
locationsRequired	object	Contains sender and recipient address information
parcelsRequired	array	Array of parcel objects containing package details
optionsRequired	object	Shipping options and carrier preferences

Locations Object

Contains sender and recipient objects with identical structure:

Field	Type	Description
company_nameRequired	string	Name of the company
contact_nameRequired	string	Name of the contact person
streetRequired	string	Street name with house number
numberOptional	string	House/building number (can be included in street)
postal_codeRequired	string	Postal/ZIP code
cityRequired	string	City name
stateOptional	string	State or province (required for some countries)
countryRequired	string	ISO 3166-1 alpha-2 country code (e.g., "NL", "US", "DE")
emailOptional	string	Email address for notifications
phoneOptional	string	Phone number with country code
address_linesOptional	array	Additional address lines if needed
registrationNumbersOptional	array	Tax or business registration numbers (e.g., VAT, EORI)

Parcels Array

Each parcel object contains:

Field	Type	Description
idOptional	string	Unique identifier for the parcel (UUID format)
container_idOptional	string	Container reference identifier (UUID format)
serial_numberOptional	string	Serial number for tracking purposes
weightRequired	object	Weight information with gross, nett (numeric), and unit ("kg" or "lb")
dimensionsRequired	object	Package dimensions with length, width, height in centimeters
itemsOptional	array	Array of item objects for customs declarations

Items Array (for customs)

Each item object contains:

Field	Type	Description
descriptionRequired	string	Description of the item for customs
quantityRequired	integer	Number of items
SKUOptional	string	Stock Keeping Unit identifier
hs_codeOptional	string	Harmonized System code for customs classification
COOOptional	string	Country of Origin (ISO 3166-1 alpha-2 code)
piece_valueOptional	object	Value per piece with amount (numeric) and currency (ISO 4217 code)

Options Object

Field	Type	Description
carrierRequired	string	Preferred carrier for the shipment (see available carriers below)
contentRequired	string	Content type: DOCUMENTS or NON_DOCUMENTS
methodRequired	string	Shipping method (e.g., create_shipment)
orderNumberOptional	string	Full order number reference (UUID format)
shipmentIdOptional	string	Shipment identifier (UUID format)
customer_referenceOptional	string	Custom reference for the customer
pickupOptional	boolean	Whether to schedule a pickup (default: false)
noEmailOptional	boolean	Disable email notifications (default: false)

Available Carriers

Example Request

{
    "shipment": {
        "ship_date": "2025-06-15 09:00:00",
        "order_number": "abc12345",
        "locations": {
            "sender": {
                "city": "Amsterdam",
                "company_name": "Example Logistics B.V.",
                "email": "sender@example.com",
                "phone": "+31 20 123 4567",
                "state": "",
                "address_lines": [],
                "contact_name": "John Doe",
                "country": "NL",
                "postal_code": "1012AB",
                "street": "Damrak 1",
                "number": "1",
                "registrationNumbers": []
            },
            "recipient": {
                "city": "Rotterdam",
                "company_name": "Recipient Company B.V.",
                "email": "recipient@example.com",
                "phone": "+31 10 987 6543",
                "state": "Zuid-Holland",
                "address_lines": [],
                "contact_name": "Jane Smith",
                "country": "NL",
                "postal_code": "3011 AA",
                "street": "Coolsingel 100",
                "number": "100",
                "registrationNumbers": []
            }
        },
        "parcels": [
            {
                "serial_number": "",
                "id": "11111111-2222-3333-4444-555555555555",
                "container_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                "weight": {
                    "gross": 25.0,
                    "nett": 25.0,
                    "unit": "kg"
                },
                "dimensions": {
                    "length": 40.0,
                    "width": 30.0,
                    "height": 20.0
                },
                "items": [
                    {
                        "COO": "NL",
                        "SKU": "SKU-001",
                        "description": "Sample Product - Box",
                        "hs_code": "1234 5678 90",
                        "piece_value": {
                            "amount": 50.0,
                            "currency": "EUR"
                        },
                        "quantity": 2
                    }
                ]
            }
        ],
        "options": {
            "carrier": "dhlParcel",
            "content": "NON_DOCUMENTS",
            "method": "create_shipment",
            "customer_reference": "CUST-REF-001",
            "orderNumber": "abc12345-6789-abcd-efgh-ijklmnopqrst",
            "shipmentId": "12345678-1234-1234-1234-123456789012",
            "pickup": false,
            "noEmail": true
        }
    }
}