Skip to main content

Create an instant shipment

POST 
/shipments

Purpose (Flow A): Create one or multiple shipments immediately (up to 10 in one request). Cargors auto-selects the carrier and creates the shipment in a single step. Use this when you do not need to compare quote options first.

Do not use this endpoint if you want to review prices before booking — use Flow B (POST /quotes → POST /accept-quote) or Flow C (POST /rfqs → quotes → accept). When called with a DEVELOPMENT API key, this endpoint validates the payload and returns a sample response only.

Duplicate reference validation​

Before processing the batch, Cargors checks pickupDetails.reference against existing pickup references and deliveryDetails.reference against existing destination references in both RFQs and shipments. Matching is exact and case-sensitive, across all shippers and statuses. Either reference matching is enough to reject the request; both do not need to match.

Pickup references must also be distinct within the request, as must delivery references. If any duplicate is found, the entire request returns HTTP 400 with error code badRequest, before any RFQ or shipment in that request is created. This validation also applies to Development API keys.

Database matches return Pickup reference or delivery reference already exists. Duplicates within the request return Pickup reference or delivery reference is duplicated in this request.

These checks do not guarantee duplicate prevention for simultaneous requests. If a creation response is lost, check the shipment list before retrying.

Request​

Responses​

Successful validation/creation of shipment request. With DEVELOPMENT keys this is a sample response; with PRODUCTION keys this is a real created shipment response.