Skip to content

Shipping API

Workflow guides for Shipping endpoints under /api-user/v1/shipping/. For authentication and signature rules, see API Overview. For field schemas, use Swagger UI at https://[your-api-domain]/api-user-doc.

Quick Check - Before You Start
  • You have a valid API Key and API Secret from your 3 Clicks administrator.
  • Strict auth is recommended for create and update operations.
  • URL-encode shipment_number when it contains / or other special characters (e.g. SHP/2026/001 → SHP%2F2026%2F001).
  • Shipping method, origin, destination, and freight status codes must exist in Site Settings › Shipping.

Base paths

Area Base path Swagger tag
Create / delete / status /api-user/v1/shipping/ v1 - Shipping
Detail / orders / quantities /api-user/v1/shipping/basic/ v1 - Shipping > Details

Workflow 1 — Get shipment detail

Retrieve a single shipment by shipment number.

  1. Confirm the shipment exists on your tenant.
  2. URL-encode the shipment number if required (see Overview — URL Encoding).
  3. Send a GET to /api-user/v1/shipping/basic/{shipmentNumber}.
curl -X 'GET' \
  'https://[your-api-domain]/api-user/v1/shipping/basic/SHP-12345' \
  -H 'accept: */*' \
  -H 'X-Api-Key: your-api-key' \
  -H 'X-Api-Signature: your-signature' \
  -H 'X-Api-Timestamp: 1717127589'

Example with encoded slash in shipment number:

GET /api-user/v1/shipping/basic/ABC%2F123

Workflow 2 — Create shipment

Create a new shipment record.

  1. Choose a unique shipment_number.
  2. Optionally set shipping method, origin, destination, dates, vessel, and freight status codes from Site Settings.
  3. Send a POST to /api-user/v1/shipping/ with a JSON body (snake_case keys).
curl -X 'POST' \
  'https://[your-api-domain]/api-user/v1/shipping/' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: your-api-key' \
  -H 'X-Api-Signature: your-signature' \
  -H 'X-Api-Timestamp: 1717128481' \
  -d '{
    "shipment_number": "SHP-API-001",
    "shipping_method_code": "SEA",
    "origin_code": "CN",
    "destination_code": "AU",
    "etd_date": "17/06/2026",
    "eta_date": "01/09/2026",
    "vessel": "Ever Given",
    "container": "CONT-12345",
    "freight_status_code": "BOOKED",
    "invoice_number": "INV-001",
    "delivery_date": "05/09/2026"
  }'

Required fields

Only shipment_number is required at create. See Swagger Shipping - Create for optional fields and validation.

Workflow 3 — Update shipment status

Change the lifecycle status of a shipment (e.g. to Completed).

  1. Use a valid status name from Site Settings › Shipping › Settings.
  2. When setting status to Completed, you may set is_update_all_associated_orders_to_completed_status to update linked orders.
  3. Send a PATCH to /api-user/v1/shipping/status/{shipmentNumber}.
curl -X 'PATCH' \
  'https://[your-api-domain]/api-user/v1/shipping/status/SHP-API-001' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: your-api-key' \
  -H 'X-Api-Signature: your-signature' \
  -H 'X-Api-Timestamp: 1717128481' \
  -d '{
    "status": "Completed",
    "is_update_all_associated_orders_to_completed_status": true
  }'

Workflow 4 — Orders and quantities (overview)

After a shipment exists, use v1 - Shipping > Details endpoints to assign orders, manage shipment quantities, and handle unassigned orders.

Operation Example path Swagger summary
Search orders to add GET …/shipping/basic/orders/option Shipping - Add Order - Find available option(s)
Create shipment quantity POST …/shipping/basic/orders/shipment-quantity/{shipmentNumber} Shipping - Orders - Shipment Quantity - Create
List unassigned orders GET …/shipping/basic/unassigned-orders/{shipmentNumber} Shipping - Unassigned Orders - List

Example — paginated order search (GET, from regression smoke test):

curl -X 'GET' \
  'https://[your-api-domain]/api-user/v1/shipping/basic/orders/option?page=1&limit=20' \
  -H 'accept: */*' \
  -H 'X-Api-Key: your-api-key' \
  -H 'X-Api-Signature: your-signature' \
  -H 'X-Api-Timestamp: 1717127589'

Full Shipping API

Browse tag v1 - Shipping > Details in Swagger UI for every order-assignment and quantity endpoint.

Further reading