openapi: 3.0.1
info:
  title: Cargoson Carriers Shipments 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.
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.
  /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:
  schemas:
    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
    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
    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
    ReturnLabelResponse:
      type: object
      description: Return label result. Exact fields are not published by Cargoson.
      additionalProperties: true
  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`.'