---
title: "Create a quote"
method: POST
path: "/quotes"
tags: ["Quotes"]
---

# Create a quote

`POST /quotes`

Create a new quote with order details.

## How it works

Creating a quote also creates an associated Order containing the route and freight details.
The Order is embedded in the Quote and cannot be managed separately.

## Required fields

- `customer`: Reference to the customer (shipper profile)
- `order`: Order details including stops and mode

## Example workflow

1. Create quote with customer and order details
2. Add pricing (amount) via PATCH
3. Send to customer (status changes to QUOTED)
4. Convert to shipment when accepted (POST /quotes/{id}/convert-to-shipment)

## Request body

- QuoteInput — Input for creating a new quote
  - `customer` union, required — Reference to another resource by either ID or client key (used in create/update requests)
    - object
      - `id` string, uuid, required — Resource UUID
      - `key` string — Client-defined reference ID
    - object
      - `id` string, uuid — Resource UUID
      - `key` string, required — Client-defined reference ID
  - `carrier` union — Reference to another resource by either ID or client key (used in create/update requests)
    - object
      - `id` string, uuid, required — Resource UUID
      - `key` string — Client-defined reference ID
    - object
      - `id` string, uuid — Resource UUID
      - `key` string, required — Client-defined reference ID
  - `order` OrderInput, required — Order definition used when creating Quotes or Shipments. Contains route (stops), freight details, and requirements.
    - `mode` 'TL' | 'LTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE', required — Transportation mode. - `TL`: Full Truckload - `LTL`: Less than Truckload - `AIR`: Air freight - `OCEAN`: Ocean freight - `RAIL`: Rail freight - `INTERMODAL`: Intermodal (multiple modes) - `DRAYAGE`: Drayage/cartage
    - `stops` OrderStopInput[], required — At least origin and destination stops
      - `type` 'PICKUP' | 'DELIVERY' | 'CROSS_DOCK', required — Type of stop
      - `location` union — Reference to another resource by either ID or client key (used in create/update requests)
        - object
          - `id` string, uuid, required — Resource UUID
          - `key` string — Client-defined reference ID
        - object
          - `id` string, uuid — Resource UUID
          - `key` string, required — Client-defined reference ID
      - `address` AddressInput — Address data for creating a new location
        - `line1` string, required — Primary street address line
        - `line2` string — Secondary address line (suite, floor, etc.)
        - `city` string, required — City name
        - `country` string, required — Country name or code
        - `market` string, required — Market or region identifier
        - `latitude` string — Latitude coordinate
        - `longitude` string — Longitude coordinate
        - `isAirportOrAirbase` boolean — Whether this location is an airport or airbase
        - `isConstructionOrUtilitySite` boolean — Whether this location is a construction or utility site
        - `isSmartyValidated` boolean — Whether address has been validated by SmartyStreets
        - `obeysDst` boolean — Whether this location observes daylight saving time
        - `cityId` string, uuid — Reference to standardized city record (internal use)
      - `requestedStartDate` string, date — Requested start date for the stop
      - `requestedEndDate` string, date — Requested end date for the stop
      - `requestedStartTime` string — Requested start time (HH:MM format)
      - `requestedEndTime` string — Requested end time (HH:MM format)
      - `appointmentRequired` boolean — Whether an appointment is required
      - `notes` string — Special instructions for the stop
    - `freight` OrderFreightInput — Freight details for an order
      - `handlingUnitQuantity` integer — Number of handling units
      - `handlingUnitType` 'PALLET' | 'SKID' | 'CARTON' | 'CRATE' | 'DRUM' | 'BUNDLE' | 'ROLL' | 'BAG' | 'TOTE' | 'OTHER' — Type of handling unit
      - `weight` number — Total weight in pounds
      - `volume` number — Total volume in cubic feet
      - `length` number — Length in inches
      - `width` number — Width in inches
      - `height` number — Height in inches
      - `commodityDescription` string — Description of the commodity
      - `hazmat` boolean — Whether freight is hazardous materials
      - `stackable` boolean — Whether freight is stackable
    - `equipment` ResourceReferenceInput[] — Equipment types required
      - union — Reference to another resource by either ID or client key (used in create/update requests)
        - object
          - `id` string, uuid, required — Resource UUID
          - `key` string — Client-defined reference ID
        - object
          - `id` string, uuid — Resource UUID
          - `key` string, required — Client-defined reference ID
    - `references` object[] — Reference numbers for the order
      - `type` string, required — Reference type (e.g., BOL_NUMBER, PO_NUMBER)
      - `value` string, required — Reference value
    - `specialRequirements` ResourceReferenceInput[] — Special requirements (e.g., liftgate, team drivers)
      - union — Reference to another resource by either ID or client key (used in create/update requests)
        - object
          - `id` string, uuid, required — Resource UUID
          - `key` string — Client-defined reference ID
        - object
          - `id` string, uuid — Resource UUID
          - `key` string, required — Client-defined reference ID
  - `amount` number — Quoted price
  - `expiresAt` string, date-time — Quote expiration
  - `assignee` union — Reference to another resource by either ID or client key (used in create/update requests)
    - object
      - `id` string, uuid, required — Resource UUID
      - `key` string — Client-defined reference ID
    - object
      - `id` string, uuid — Resource UUID
      - `key` string, required — Client-defined reference ID

## Response `201`

Quote created successfully

- Quote
  - `id` string, uuid, required — Unique identifier
  - `key` string, required — Human-readable quote ID (e.g., "Q003602")
  - `side` 'SELL' | 'BUY', required — Quote direction. - `SELL`: Selling to shipper (customer quote) - `BUY`: Buying from carrier (carrier quote)
  - `status` 'DRAFT' | 'REQUESTED' | 'QUOTED' | 'RECEIVED_REPLY' | 'SENT_REPLY' | 'RECEIVED_COUNTER' | 'SENT_COUNTER' | 'WON' | 'LOST' | 'PASS' | 'CANCELED', required — Current status in the quote lifecycle. Initial states: - `DRAFT`: Quote being drafted - `REQUESTED`: Customer requested a quote (needs pricing) Active states: - `QUOTED`: Price sent to customer - `RECEIVED_REPLY`: Received reply from customer - `SENT_REPLY`: Sent reply to customer - `RECEIVED_COUNTER`: Received counter-offer - `SENT_COUNTER`: Sent counter-offer Final states: - `WON`: Customer accepted the quote - `LOST`: Quote not accepted - `PASS`: Broker declined to quote - `CANCELED`: Quote canceled
  - `amount` number, nullable — Quoted price
  - `target` number, nullable — Target price for margin calculation
  - `margin` number, nullable — Calculated margin percentage
  - `expiresAt` string, date-time, nullable — Quote expiration timestamp
  - `customer` CustomerReference — Enhanced reference to a customer resource (returned in responses). Includes full customer details in addition to id/key. Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion. Maximum nesting depth: 1 level.
    - `id` string, uuid, required — Customer UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `name` string, required — Customer company name
    - `friendlyId` string, required — Human-readable customer identifier
    - `status` 'PROSPECT' | 'ACTIVE' | 'INACTIVE' | 'CHURNED', required — Customer status
    - `phoneNumber` string, nullable — Primary phone number
    - `website` string, nullable — Customer website URL
    - `createdAt` string, date-time, required — When the customer was created
    - `updatedAt` string, date-time, required — When the customer was last updated
    - `deletedAt` string, date-time, nullable — When the customer was soft deleted (null if active)
  - `carrier` CarrierReference — Enhanced reference to a carrier resource (returned in responses). Includes full carrier details in addition to id/key. Note: Does NOT include nested references (contacts, etc.) to prevent recursion. Maximum nesting depth: 1 level.
    - `id` string, uuid, required — Carrier UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `name` string, required — Carrier company name
    - `phoneNumber` string, nullable — Primary phone number
    - `email` string, email, nullable — Primary email address
    - `createdAt` string, date-time, required — When the carrier was created
    - `updatedAt` string, date-time, required — When the carrier was last updated
    - `deletedAt` string, date-time, nullable — When the carrier was soft deleted (null if active)
  - `order` OrderSummary — Summary of order details (embedded in Quote response)
    - `id` string, uuid
    - `key` string, nullable
    - `mode` 'TL' | 'LTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE' — Transportation mode. - `TL`: Full Truckload - `LTL`: Less than Truckload - `AIR`: Air freight - `OCEAN`: Ocean freight - `RAIL`: Rail freight - `INTERMODAL`: Intermodal (multiple modes) - `DRAYAGE`: Drayage/cartage
    - `origin` object
      - `city` string
      - `stateProvince` string
      - `postalCode` string, nullable
    - `destination` object
      - `city` string
      - `stateProvince` string
      - `postalCode` string, nullable
    - `pickUpDate` string, date, nullable
    - `deliveryDate` string, date, nullable
    - `equipment` string[]
    - `weight` number, nullable
    - `mileage` number, nullable
  - `lostReason` 'EXPIRED' | 'NO_REASON' | 'NO_RESPONSE' | 'TOO_HIGH' | 'TOO_SLOW' | 'TRUCK_NOT_AVAILABLE' | 'OTHER' — Reason why the quote was lost. - `EXPIRED`: Quote expired without response - `NO_REASON`: No specific reason given - `NO_RESPONSE`: Customer didn't respond - `TOO_HIGH`: Price was too high - `TOO_SLOW`: Response was too slow - `TRUCK_NOT_AVAILABLE`: Capacity not available - `OTHER`: Other reason (see lostReasonText)
  - `lostReasonText` string, nullable — Additional text for lost reason
  - `closedTime` string, date-time, nullable — When the quote was closed (won/lost)
  - `assignee` UserReference — Enhanced reference to a user resource (returned in responses). Includes full user details in addition to id/key. Note: Does NOT include nested references (teams, etc.) to prevent recursion. Maximum nesting depth: 1 level.
    - `id` string, uuid, required — User UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `email` string, email, required — User's email address
    - `name` string, nullable — User's full name
    - `phone` string, nullable — User's phone number
    - `phoneExt` string, nullable — Phone extension
    - `status` 'PENDING' | 'ACTIVE' | 'INACTIVE', required — User account status
    - `avatarId` string, uuid, nullable — Profile avatar document ID
    - `createdAt` string, date-time, required — When the user was created
    - `updatedAt` string, date-time, required — When the user was last updated
    - `deletedAt` string, date-time, nullable — When the user was soft deleted (null if active)
  - `shipmentId` string, uuid, nullable — Shipment ID if converted
  - `shipmentKey` string, nullable — Shipment friendly ID if converted
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, nullable

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `422` — Validation error - invalid field values

---

[API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/revisions/c44e5e7a4256/schema)