Cargomatic Shipper API

openapi: 3.0.0
info:
  title: Cargomatic Public Authorization Shipper API
  description: '## Welcome to the Cargomatic API!

    Our quoting, booking, and status APIs allow you to automate common workflows similar to features available within the Cargomatic portal.


    Please reach out to [apisupport@cargomatic.com](apisupport@cargomatic.com) for sandbox credentials to get started.'
  version: 3.0.0
servers:
- url: https://api-acceptance.cargomatic.com
tags:
- name: Shipper
  description: Endpoints for Cargomatic Shippers
paths:
  /quotes:
    post:
      operationId: createQuote
      summary: Creates a quote
      description: 'Creates a quote based on the factors provided in the request body.

        This API endpoint is only accessible by Shippers and Admins!'
      tags:
      - Shipper
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: 'Status Code 200:  Successful Response - the request was successful!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '500':
          description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /orders:
    post:
      operationId: createOrder
      summary: Creates an order
      description: Creates an order based on the factors provided in the request body. This API endpoint can only be accessed by Shippers!
      tags:
      - Shipper
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '200':
          description: 'Status Code 200:  Successful Response - the request was successful!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '500':
          description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /shipments:
    post:
      operationId: createShipment
      summary: Create a shipment/offer
      description: 'Creates a shipment based on the factors provided in the request body. This API endpoint can only be accessed by Admins and Shippers!

        `action` - add, update, cancel'
      tags:
      - Shipper
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferRequest'
      responses:
        '200':
          description: 'Status Code 200:  Successful Response - the request was successful!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferResponse'
        '400':
          description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '500':
          description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
    get:
      operationId: listShipments
      summary: Lists all shipments with a pagination option
      tags:
      - Shipper
      security:
      - bearerAuth: []
      parameters:
      - name: page
        in: query
        description: Page number, indicates the page of results that you want returned. Default value is 1.
        required: false
        schema:
          type: number
      - name: per_page
        in: query
        description: \# of results per page
        required: false
        schema:
          type: number
      responses:
        '200':
          description: 'Status Code 200:  Successful Response - the request was successful!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentResponse'
        '400':
          description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '500':
          description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /shipments/status:
    get:
      operationId: shipmentStatus
      summary: Returns a shipment with status info
      description: ''
      tags:
      - Shipper
      security:
      - bearerAuth: []
      parameters:
      - name: shipmentReference
        in: query
        description: Shipment Id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Status Code 200:  Successful Response - the request was successful!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentResponse'
        '400':
          description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '500':
          description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /webhooks/loads:
    post:
      operationId: processLoads
      summary: Process loads
      tags:
      - Shipper
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json: {}
      responses:
        '204':
          description: Status 204 Response
  /stops/complete:
    post:
      operationId: completeStop
      summary: Mark a stop as complete
      description: Marks a stop as "complete". The `stopId`, and `shipmentReference` is required for all shipment types. If the shipment is shorthaul, only admins can access this route and file data must also be provided. If the shipment is drayage, `chassis`, `trailerId`, and `containerId` may be required.
      tags:
      - Shipper
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteStopRequest'
      responses:
        '200':
          description: 'Status Code 200:  Successful Response - the request was successful!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompleteStopResponse'
        '400':
          description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /stops/transition:
    post:
      operationId: arriveAtStop
      summary: Mark a stop as "arrived"
      description: 'Marks a stop as "arrived". `status`, `stopId`, and `shipmentReference` are required. The only acceptable value for `status` is `arrived` (see example request body). If `date` is not provided, the current time will be used as the arrival time.

        Admins, shippers, carriers, and drivers are authorized to use this API endpoint.'
      tags:
      - Shipper
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArriveAtStopRequest'
      responses:
        '200':
          description: 'Status Code 200:  Successful Response - the request was successful!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArriveAtStopResponse'
        '400':
          description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '500':
          description: 'Status Code 500: Internal Server Error Response - there''s a problem with the Public API service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /stops/add:
    post:
      operationId: addStop
      summary: Add additional stops to a shipment
      description: '`shipmentReference` and at least one new stop are required. Each new stop must include `address`, `action`, `name`, `sequence`, `windowStart`, `windowEnd`, and other fields dependent on the type of shipment.

        For US-based clients, the address must include street address, city, state, and zipcode. The `action` is either "pickup" or "delivery". The sequence number is sequence of the stop within the shipment. The `name` of the stop is the location name. `windowStart` is when the pickup/delivery window starts for that stop. `windowEnd` is when the pickup/delivery window ends for that stop.

        If the shipment is shorthaul, the new stop must include load data and it must be indicated whether the cargo is a full truckload or not. If the shipment is drayage, the new stop must indicate whether the container is empty or not and location must be included.'
      tags:
      - Shipper
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddStopRequest'
      responses:
        '200':
          description: 'Status Code 200:  Successful Response - the request was successful!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddStopResponse'
        '400':
          description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '500':
          description: 'Status Code 500: Internal Server Error Response - there''s a problem with the Public API service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
components:
  schemas:
    QuoteRequestStops:
      type: object
      required:
      - action
      - location
      properties:
        action:
          type: string
          example: pickup
          description: Acceptable values for `action` are `pickup` and  `deliver`.
        location:
          type: object
          required:
          - name
          - address
          properties:
            name:
              type: string
              example: Atlas Marine
            address:
              type: string
              example: 1550 Cota Ave Long Beach CA 90813
    AddStopRequest:
      type: object
      required:
      - shipmentReference
      - newStops
      properties:
        shipmentReference:
          type: string
          example: ABC-123
        newStops:
          type: array
          items:
            type: object
            required:
            - sequence
            - address
            - action
            - name
            - windowStart
            - windowEnd
            properties:
              sequence:
                type: number
                example: 1
              address:
                type: string
                example: 1550 Cota Ave, Long Beach, CA 90813, USA
              action:
                type: string
                example: pickup
              name:
                type: string
                example: Atlas Marine
              windowStart:
                type: string
                example: '2023-01-01T21:00:00.000Z'
              windowEnd:
                type: string
                example: '2024-01-01T21:00:00.000Z'
              fullTruckload:
                type: boolean
                example: false
              isEmptyContainer:
                type: boolean
                example: true
              loads:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: pallets
                    quantity:
                      type: number
                    width:
                      type: number
                    length:
                      type: number
    OrderRequestShipmentsStagingStops:
      type: object
      properties:
        sequence:
          type: integer
          format: int32
          example: 1
        action:
          type: string
          example: pickup
        empty:
          type: boolean
        location:
          $ref: '#/components/schemas/OrderRequestLocation'
        window_start:
          type: string
          format: date-time
          example: 2022-09-09 19:00:45.440000+00:00
        window_end:
          type: string
          format: date-time
          example: 2022-09-09 22:00:50.317000+00:00
        equipments:
          type: array
          items:
            type: object
            properties:
              equipment_id:
                type: string
                example: AAAU1231234
              _equipmentType:
                type: string
                example: container
    InternalServerErrorResponse:
      type: object
      properties:
        message:
          type: string
      example:
        message: Internal Server Error
    QuoteResponse:
      type: object
      properties:
        success:
          type: boolean
        quote:
          type: object
          properties:
            full_truckload:
              type: boolean
            shipment_type:
              type: string
              example: shorthaul
            weight:
              type: integer
              format: int32
              example: 4000
            distance:
              type: integer
              format: int32
              example: 4276
            courier:
              type: boolean
            created_at:
              type: string
              format: date-time
              example: 2023-07-12 03:41:08.784000+00:00
            total_cost:
              type: string
              example: 190.85
            origin:
              type: object
              properties:
                address:
                  type: string
                  example: 1550 Cota Ave Long Beach CA 90813 USA
                coords:
                  type: array
                  items:
                    type: number
                    example: -118.2162816
                name:
                  type: string
                  example: Atlas Marine
            destination:
              type: object
              properties:
                address:
                  type: string
                  example: 211 E Ocean Blvd Long Beach CA 90802
                coords:
                  type: array
                  items:
                    type: number
                    example: -118.19072819999997
                name:
                  type: string
                  example: Cargomatic
            loads:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    example: pallets
                  dimensional_units:
                    type: string
                    example: in
                  quantity:
                    type: integer
                    format: int32
                    example: 3
                  width:
                    type: integer
                    format: int32
                    example: 40
                  height:
                    type: integer
                    format: int32
                    example: 60
                  length:
                    type: integer
                    format: int32
                    example: 48
                  weight:
                    type: integer
                    format: int32
                    example: 4000
                  spaces:
                    type: integer
                    format: int32
                    example: 3
                  weight_units:
                    type: string
                    example: lb
                  _id:
                    type: string
                    example: 64ae20d4814c928bbafbeade
            quote_id:
              type: string
              example: BAD-QT-1796
            expiration_date:
              type: string
              format: date-time
              example: 2023-07-19 03:41:08+00:00
            receivables:
              type: array
              items:
                type: object
                properties:
                  message:
                    type: string
                    example: Residential
                  value:
                    type: integer
                    format: int32
                    example: 35
                  timestamp:
                    type: string
                    format: date-time
                    example: 2023-07-12 03:41:06.029000+00:00
            shipper:
              type: string
              example: badri.shipper@cargomatic.com
    OrderRequestShipmentsStaging:
      type: object
      properties:
        weight:
          type: integer
          format: int32
          example: 35000
        stops:
          type: array
          items:
            $ref: '#/components/schemas/OrderRequestShipmentsStagingStops'
    QuoteRequest:
      type: object
      required:
      - full_truckload
      - stops
      - weight
      properties:
        accessorials:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: residential_delivery
                description: Allowed values for type are `cfs`, `hazmat`, `liftgate_origin`, `liftgate_destination`, `residential_delivery`, `room_of_choice`, `white_glove`, `airport_pickup`, `tsa_certification`, `flatbed_truck`, `two_man` and `inside_delivery`.
        courier:
          type: boolean
        distance:
          type: integer
          format: int32
          example: 12583
        loads:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/QuoteRequestLoads'
        market:
          type: string
          example: SFO
          description: The valid values for `market` are the three letter identifiers for the market, like LAX, SFO, ATL, etc.
        stops:
          type: array
          items:
            $ref: '#/components/schemas/QuoteRequestStops'
        weight:
          description: Total weight of the shipment.
          type: integer
          format: int32
          example: 40000
        weight_units:
          description: Default unit is `lb`.
          type: string
          example: lb
        shipper:
          type: object
          properties:
            _id:
              type: string
              example: 62879ea006bfa2d915861ba6
        full_truckload:
          type: boolean
          example: true
          description: If `full_truckload` is `false`, `loads` is a required field.
        shipment_type:
          type: string
          example: shorthaul
    CompleteStopResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            stopId:
              type: string
            status:
              type: string
              example: complete
            locationName:
              type: string
            locationAddress:
              type: string
            windowStart:
              type: string
              example: '2021-06-02T15:54:29.728Z'
            windowEnd:
              type: string
              example: '2021-07-02T15:54:29.728Z'
            appointmentConfirmed:
              type: boolean
            complete:
              type: boolean
            missingDocs:
              type: boolean
            documents:
              type: array
              items:
                type: string
                example: stop_info.txt
    OrderRequestLocation:
      type: object
      required:
      - name
      - address
      properties:
        name:
          type: string
          example: APMT
          description: Name of the location. Can be an internal identifier, name of the location (ex. LAX Terminal 7), etc.
        address:
          type: string
          example: 2500 Navy Way San Pedro CA 90731
          description: US-based addresses must include street address, suite (if applicable), state, and zip code.
    AddStopResponse:
      type: object
      properties:
        success:
          type: boolean
        shipment:
          type: object
          properties:
            market:
              type: object
              properties:
                name:
                  type: string
                  example: San Antonio
                code:
                  type: string
                  example: SAT
            _id:
              type: string
            shipment_id:
              type: string
              example: ABC-123
            stops:
              type: array
              items:
                type: object
                properties:
                  _id:
                    type: string
                    example: stopID123
                  action:
                    type: string
                    example: deliver
                  full_truckload:
                    type: boolean
                    example: false
                  location:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 1234567890z9310
                        address:
                          type: string
                          example: 211 E. Ocean Blvd, Suite 350, Long Beach, CA 90802, USA
                        street:
                          type: string
                          example: 211 E. Ocean Blvd
                        suite_or_apt:
                          type: string
                          example: Suite 350
                        zipcode:
                          type: string
                          example: '90802'
                        city:
                          type: string
                          example: Long Beach
                        state:
                          type: string
                          example: CA
                        lng:
                          type: number
                          example: -123.456789
                        lat:
                          type: number
                          example: 37.1234567
                  status:
                    type: string
                    example: unstarted
                  shipment_type:
                    type: string
                    example: shorthaul
                  sequence:
                    type: number
                    example: 2
                  window_start:
                    type: string
                    example: 2023-07-24 23:30:00+00:00
                  window_end:
                    type: string
                    example: 2023-07-24 23:30:00+00:00
    OfferResponse:
      type: object
      properties:
        action:
          type: string
          example: add
        shipment:
          type: object
          properties:
            shipment_type:
              type: string
              example: shorthaul
            shipper:
              type: string
              example: shipper@cargomatic.com
            reference_numbers:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: My Primary Reference
                  value:
                    type: string
                    example: cargomatic123
                  primary:
                    type: boolean
            stops:
              type: array
              items:
                type: object
                properties:
                  sequence:
                    type: integer
                    format: int32
                    example: 1
                  location:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Cargomatic HQ
                      address:
                        type: string
                        example: 211 E. Ocean Blvd Long Beach CA 90802
                      suite_or_apt:
                        type: string
                        example: Suite 350
                  loads:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: pallets
                        quantity:
                          type: integer
                          format: int32
                          example: 5
                        width:
                          type: integer
                          format: int32
                          example: 40
                        height:
                          type: integer
                          format: int32
                          example: 48
                        length:
                          type: integer
                          format: int32
                          example: 40
                        weight:
                          type: integer
                          format: int32
                          example: 2500
                  contacts:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: support
                        email:
                          type: string
                          example: support@cargomatic.com
                        phone:
                          type: string
                          example: 555-555-5555
                  action:
                    type: string
                    example: pickup
                  window_start:
                    type: string
                    format: date-time
                    example: 2022-03-31 18:00:00+00:00
                  window_end:
                    type: string
                    format: date-time
                    example: 2022-03-31 21:00:00+00:00
                  reference_numbers:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: My Stop Reference Number
                        value:
                          type: string
                          example: cargomatic123456
            loads:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    example: pallets
                  quantity:
                    type: integer
                    format: int32
                    example: 5
                  width:
                    type: integer
                    format: int32
                    example: 40
                  height:
                    type: integer
                    format: int32
                    example: 48
                  length:
                    type: integer
                    format: int32
                    example: 40
                  weight:
                    type: integer
                    format: int32
                    example: 2500
            accessorials:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    example: pallet_jack
            weight:
              type: integer
              format: int32
              example: 2500
            notes:
              type: string
              example: These are my notes!
    BadRequestResponse:
      type: object
      properties:
        message:
          type: string
      example:
        message: Invalid Request Body
    QuoteRequestLoads:
      type: object
      description: 'If `full_truckload` is `false`, `loads` data are required:  `loads` must contain at least one entry and the required data for each entry is `quantity`, `length`, `width`, `height`, and `weight`.'
      required:
      - quantity
      - height
      - length
      - width
      - dimensional_units
      - weight_units
      - type
      properties:
        type:
          type: string
          example: pallets
        quantity:
          type: integer
          format: int32
          example: 1
        length:
          type: integer
          format: int32
          example: 48
        width:
          type: integer
          format: int32
          example: 40
        height:
          type: integer
          format: int32
          example: 60
        weight:
          type: integer
          format: int32
          example: 0
        weight_units:
          type: string
          example: lb
          description: Default value is `lb`.
        dimensional_units:
          type: string
          example: in
          description: Default value is `in`.
        languageCodeId:
          type: string
          example: en-us
        distance_units:
          type: string
          example: mi
        currency:
          type: string
          example: USD
        temperature_units:
          type: string
          example: F
        stackable:
          type: boolean
          example: false
          description: Default value is `false`.
    ArriveAtStopResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            shipmentReference:
              type: string
            status:
              type: string
              example: arrived
            stopId:
              type: string
            meta:
              type: object
              properties:
                date:
                  type: string
    ArriveAtStopRequest:
      type: object
      properties:
        shipmentReference:
          type: string
          example: ABC-123
        stopId:
         

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cargomatic/refs/heads/main/openapi/cargomatic-shipper-api-openapi.yml