API Documentation: Shipment Tracking REST API

Endpoints

• GET /shipments: Your shipments and your teams' shipments, most recently updated first.
• GET /shipments/{id}: One shipment with all list fields plus container or flight details, vessel position, delay reason, and milestones.
• POST /shipments: Creates a shipment and starts tracking it, exactly like adding it in CargoEnter. It uses one credit from your plan or paid credits, the same as in the app. Send an Idempotency-Key header so a retry never creates it twice.
• GET /me: The account behind the key: plan, available credits, teams, and your limits. Handy for checking that a key works.
• GET /teams: Teams you own or belong to. Use the IDs to filter shipments or create team shipments.
• GET /projects: Projects you can see, with their team.

Shipment fields

• id (string (UUID)): Unique shipment ID. Use it with GET /shipments/{id}.
• name (string): The shipment name you gave it in CargoEnter.
• type (string): container, air, truck, rail, or other.
• reference_number (string | null): Container number, AWB number, or your own reference.
• status (string | null): Shipment status in CargoEnter, for example Draft, In transit, Arrived.
• is_mine (boolean): true if you own the shipment, false if a team member owns it.
• team (object | null): The team the shipment belongs to: id, name.
• project (object | null): The project the shipment belongs to: id, name.
• carrier (string | null): Shipping line or airline.
• origin (object | null): Port or airport of departure: name, code (UN/LOCODE or IATA).
• destination (object | null): Port or airport of arrival: name, code.
• destination_country (string | null): 2-letter ISO country code, if set.
• departure.estimated (string | null (ISO 8601)): Estimated departure (ETD).
• departure.actual (string | null (ISO 8601)): Actual departure (ATD) or flight date.
• arrival.estimated (string | null (ISO 8601)): Current estimated arrival (ETA).
• arrival.original_estimate (string | null (ISO 8601)): The first ETA we received. Compare it with arrival.estimated to see delays.
• arrival.actual (string | null (ISO 8601)): Actual arrival (ATA).
• tracking.current_status (string | null): Latest status from the carrier, for example "Vessel departed".
• tracking.current_location (string | null): Latest location reported by the carrier (air shipments).
• tracking.is_delayed (boolean): true when the carrier data shows a delay.
• tracking.last_update (string | null (ISO 8601)): When the tracking data was last updated.
• public_url (string | null): Link to the public tracking page, if you made the shipment public.
• created_at (string (ISO 8601)): When the shipment was created.
• updated_at (string (ISO 8601)): When the shipment last changed.
• container (object | null): Ocean only: number, size (20, 40, 45), type, high_cube.
• vessel (object | null): Ocean only: name, imo, voyage, position (latitude, longitude) when known.
• flight (object | null): Air only: awb_number, flight_number, flight_date.
• cargo (object | null): Air only: pieces, weight_kg.
• delay_reason (string | null): Why the shipment is delayed, when known.
• milestones (array): Tracking events, oldest first. Each has description, location, location_code, timestamp, and type ("actual" or "planned").

Errors

• 401 missing_api_key: No key was sent. Add the Authorization header.
• 401 invalid_api_key: The key is wrong or was deleted.
• 402 insufficient_credits: Not enough credits to create a shipment.
• 403 forbidden: You have no permission for this team or project.
• 404 not_found: The shipment does not exist in your account, or the endpoint does not exist.
• 409 duplicate_reference: A shipment with this reference number already exists.
• 422 validation_error: A parameter is missing or not valid. See error.details.
• 429 rate_limit_exceeded: More than 60 requests in a minute. Wait for X-RateLimit-Reset.
• 429 daily_limit_exceeded: More than 10,000 requests today.
• 429 too_many_failed_attempts: Too many requests with a wrong key from your IP address. Blocked for 15 minutes.
• 500 server_error: Something went wrong on our side. Retry later and send us the request_id.

Frequently asked questions