Retrieve live freight rate quotes across activated carriers via POST /freightPrices/list, comparing cost, speed, and service level before selecting a carrier. Prices are pulled directly from each carrier's system.
openapi: 3.0.1
info:
title: Cargoson API
description: >-
Cargoson is a multi-carrier transport management (TMS) REST API. It exposes a
single, unified interface for requesting freight rates, creating shipment
queries and direct bookings, retrieving labels and tracking details, and
listing carrier services across 2,000+ carriers. Authentication uses an API
key as a Bearer token. Requests must send an Accept header of
`application/vnd.api.v1`. Endpoints and field names below reflect Cargoson's
public integration documentation; request/response schemas not published by
Cargoson are intentionally left open (additionalProperties true) rather than
fabricated.
termsOfService: https://www.cargoson.com/en/terms
contact:
name: Cargoson Support
url: https://www.cargoson.com/en/integrations
version: '1'
servers:
- url: https://www.cargoson.com/api/v1
description: Cargoson production API (v1)
security:
- bearerAuth: []
tags:
- name: Shipments
description: Create shipment queries and direct bookings, retrieve labels.
- name: Price Requests
description: Retrieve live freight rate quotes across activated carriers.
- name: Transports & Tracking
description: Retrieve booking, transport, and tracking details.
- name: Carriers
description: List carrier services available on the account.
paths:
/queries:
post:
operationId: createQuery
tags:
- Shipments
summary: Create a shipment query or direct booking
description: >-
Creates a transport request. In query mode the request is created
without selecting a carrier so prices and delivery times can be compared
later. Supplying options[direct_booking_service_id] books directly with
the chosen carrier service.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequest'
responses:
'200':
description: Query or booking created.
content:
application/json:
schema:
$ref: '#/components/schemas/BookingResponse'
'401':
description: Missing or invalid API key.
'422':
description: Validation error in the request body.
/freightPrices/list:
post:
operationId: listFreightPrices
tags:
- Price Requests
summary: Get freight rate quotes
description: >-
Returns live freight rate quotes and available services from the
carriers activated on the account, based on the supplied collection,
delivery, and shipment row details.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FreightPriceListRequest'
responses:
'200':
description: List of freight price quotes.
content:
application/json:
schema:
$ref: '#/components/schemas/FreightPriceListResponse'
'401':
description: Missing or invalid API key.
'422':
description: Validation error in the request body.
/services/list:
get:
operationId: listServices
tags:
- Carriers
summary: List carrier services available on the account
description: >-
Returns the list of carrier services available on your company account.
Service identifiers can be used as direct_booking_service_id when
creating a direct booking.
responses:
'200':
description: List of available carrier services.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceListResponse'
'401':
description: Missing or invalid API key.
/bookings/{reference}:
get:
operationId: getBooking
tags:
- Transports & Tracking
summary: Retrieve booking and tracking details
description: >-
Retrieves transport and tracking details for an existing shipment using
the Cargoson booking reference.
parameters:
- name: reference
in: path
required: true
description: Cargoson booking reference.
schema:
type: string
responses:
'200':
description: Booking and tracking details.
content:
application/json:
schema:
$ref: '#/components/schemas/BookingResponse'
'401':
description: Missing or invalid API key.
'404':
description: Booking reference not found.
/bookings/{reference}/return_labels:
post:
operationId: createReturnLabel
tags:
- Shipments
summary: Create a return label for an existing shipment
description: >-
Generates a return shipping label for an existing booking identified by
its Cargoson booking reference.
parameters:
- name: reference
in: path
required: true
description: Cargoson booking reference.
schema:
type: string
responses:
'200':
description: Return label created.
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnLabelResponse'
'401':
description: Missing or invalid API key.
'404':
description: Booking reference not found.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API key passed as a Bearer token in the Authorization header
(`Authorization: Bearer YOUR_API_KEY`). Requests must also send
`Accept: application/vnd.api.v1`.
schemas:
ShipmentRow:
type: object
description: A single line/row in a shipment.
properties:
quantity:
type: integer
description: Number of packages.
package_type:
type: string
description: Package type code (e.g. pallet, parcel, box).
weight:
type: number
description: Weight of the row.
description:
type: string
description: Goods description.
additionalProperties: true
QueryRequest:
type: object
description: >-
Shipment query / booking request. Collection and delivery details are
supplied inline. Field names reflect Cargoson's documented integration
examples.
properties:
collection_date:
type: string
description: Requested collection date.
collection_country:
type: string
description: Collection country code.
collection_postcode:
type: string
collection_address_row_1:
type: string
collection_city:
type: string
collection_company_name:
type: string
collection_contact_name:
type: string
collection_contact_phone:
type: string
delivery_country:
type: string
description: Delivery country code.
delivery_postcode:
type: string
delivery_address_row_1:
type: string
delivery_city:
type: string
delivery_company_name:
type: string
delivery_contact_name:
type: string
delivery_contact_phone:
type: string
rows_attributes:
type: array
description: Shipment rows.
items:
$ref: '#/components/schemas/ShipmentRow'
options:
type: object
description: Booking options.
properties:
direct_booking_service_id:
type: integer
description: >-
Carrier service ID (from the services or freight price list) to
book directly with the chosen carrier.
additionalProperties: true
additionalProperties: true
FreightPriceListRequest:
type: object
description: >-
Request for freight rate quotes. Uses the same collection, delivery, and
rows_attributes structure as a query.
properties:
collection_country:
type: string
collection_postcode:
type: string
collection_city:
type: string
delivery_country:
type: string
delivery_postcode:
type: string
delivery_city:
type: string
rows_attributes:
type: array
items:
$ref: '#/components/schemas/ShipmentRow'
additionalProperties: true
FreightPrice:
type: object
description: A single carrier rate quote. Exact fields vary by carrier.
additionalProperties: true
FreightPriceListResponse:
type: object
description: Collection of freight price quotes.
properties:
data:
type: array
items:
$ref: '#/components/schemas/FreightPrice'
additionalProperties: true
Service:
type: object
description: A carrier service available on the account.
properties:
id:
type: integer
description: Service identifier usable as direct_booking_service_id.
name:
type: string
description: Service name.
additionalProperties: true
ServiceListResponse:
type: object
description: List of carrier services.
properties:
data:
type: array
items:
$ref: '#/components/schemas/Service'
additionalProperties: true
BookingResponse:
type: object
description: >-
Booking, transport, and tracking details. Exact response fields are not
published by Cargoson; left open rather than fabricated.
properties:
reference:
type: string
description: Cargoson booking reference.
additionalProperties: true
ReturnLabelResponse:
type: object
description: Return label result. Exact fields are not published by Cargoson.
additionalProperties: true