# Update a quote

Update quote fields including status changes.

## Status changes

Status changes use this endpoint (not separate action endpoints):
- Set to QUOTED: { "status": "QUOTED", "amount": 2500 }
- Set to WON: { "status": "WON" }
- Set to LOST: { "status": "LOST", "lostReason": "TOO_HIGH" }

## Validation rules

- When setting status to LOST, lostReason is required
- When lostReason is OTHER, lostReasonText is required

## Note

To convert a won quote to a shipment, use POST /quotes/{id}/convert-to-shipment

Endpoint: PATCH /quotes/{id}
Version: 1.0.0
Security: BearerAuth

## Path parameters:

  - `id` (string, required)
    Resource ID (UUID) or client key
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Query parameters:

  - `by` (string)
    Specify lookup type for faster retrieval.
If omitted, defaults to looking up by ID first, then falls back to client key if not found.
Use by=key when you know you're providing a client key for best performance.
    Enum: "id", "key"

## Request fields (application/json):

  - `status` (string)
    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
    Enum: "DRAFT", "REQUESTED", "QUOTED", "RECEIVED_REPLY", "SENT_REPLY", "RECEIVED_COUNTER", "SENT_COUNTER", "WON", "LOST", "PASS", "CANCELED"

  - `amount` (number,null)

  - `target` (number,null)

  - `expiresAt` (string,null)

  - `lostReason` (string)
    Required when status is LOST
    Enum: "EXPIRED", "NO_REASON", "NO_RESPONSE", "TOO_HIGH", "TOO_SLOW", "TRUCK_NOT_AVAILABLE", "OTHER"

  - `lostReasonText` (string)
    Required when lostReason is OTHER

  - `assignee` (any)

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `key` (string, required)
    Human-readable quote ID (e.g., "Q003602")
    Example: "Q003602"

  - `side` (string, required)
    Quote direction.
- SELL: Selling to shipper (customer quote)
- BUY: Buying from carrier (carrier quote)
    Enum: "SELL", "BUY"

  - `status` (string, 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
    Enum: "DRAFT", "REQUESTED", "QUOTED", "RECEIVED_REPLY", "SENT_REPLY", "RECEIVED_COUNTER", "SENT_COUNTER", "WON", "LOST", "PASS", "CANCELED"

  - `amount` (number,null)
    Quoted price
    Example: 2500

  - `target` (number,null)
    Target price for margin calculation
    Example: 2200

  - `margin` (number,null)
    Calculated margin percentage
    Example: 12

  - `expiresAt` (string,null)
    Quote expiration timestamp

  - `customer` (object)
    Customer (for SELL quotes)

  - `customer.id` (string, required)
    Customer UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `customer.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CUSTOMER-ACME"

  - `customer.name` (string, required)
    Customer company name
    Example: "Acme Manufacturing Corp"

  - `customer.friendlyId` (string, required)
    Human-readable customer identifier
    Example: "A123456"

  - `customer.status` (string, required)
    Customer status
    Enum: "PROSPECT", "ACTIVE", "INACTIVE", "CHURNED"

  - `customer.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `customer.website` (string,null)
    Customer website URL
    Example: "https://acme-manufacturing.com"

  - `customer.createdAt` (string, required)
    When the customer was created
    Example: "2025-01-15T10:00:00Z"

  - `customer.updatedAt` (string, required)
    When the customer was last updated
    Example: "2025-01-15T14:30:00Z"

  - `customer.deletedAt` (string,null)
    When the customer was soft deleted (null if active)

  - `carrier` (object)
    Carrier (for BUY quotes)

  - `carrier.id` (string, required)
    Carrier UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `carrier.name` (string, required)
    Carrier company name
    Example: "Swift Transportation"

  - `carrier.email` (string,null)
    Primary email address
    Example: "dispatch@swifttrans.com"

  - `carrier.createdAt` (string, required)
    When the carrier was created
    Example: "2025-01-15T10:00:00Z"

  - `carrier.updatedAt` (string, required)
    When the carrier was last updated
    Example: "2025-01-15T14:30:00Z"

  - `carrier.deletedAt` (string,null)
    When the carrier was soft deleted (null if active)

  - `order` (object)
    Order details (route, freight)

  - `order.id` (string)

  - `order.key` (string,null)

  - `order.mode` (string)
    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
    Enum: "TL", "LTL", "AIR", "OCEAN", "RAIL", "INTERMODAL", "DRAYAGE"

  - `order.origin` (object)

  - `order.origin.city` (string)

  - `order.origin.stateProvince` (string)

  - `order.origin.postalCode` (string,null)

  - `order.destination` (object)

  - `order.pickUpDate` (string,null)

  - `order.deliveryDate` (string,null)

  - `order.equipment` (array)

  - `order.weight` (number,null)

  - `order.mileage` (number,null)

  - `lostReason` (any)
    Why the quote was lost

  - `lostReasonText` (string,null)
    Additional text for lost reason

  - `closedTime` (string,null)
    When the quote was closed (won/lost)

  - `assignee` (object)
    Assigned sales rep

  - `assignee.id` (string, required)
    User UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `assignee.email` (string, required)
    User's email address
    Example: "john.doe@example.com"

  - `assignee.name` (string,null)
    User's full name
    Example: "John Doe"

  - `assignee.phone` (string,null)
    User's phone number
    Example: "+1-555-123-4567"

  - `assignee.phoneExt` (string,null)
    Phone extension
    Example: "123"

  - `assignee.status` (string, required)
    User account status
    Enum: "PENDING", "ACTIVE", "INACTIVE"

  - `assignee.avatarId` (string,null)
    Profile avatar document ID
    Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

  - `assignee.createdAt` (string, required)
    When the user was created
    Example: "2025-01-15T10:00:00Z"

  - `assignee.updatedAt` (string, required)
    When the user was last updated
    Example: "2025-01-15T14:30:00Z"

  - `assignee.deletedAt` (string,null)
    When the user was soft deleted (null if active)

  - `shipmentId` (string,null)
    Shipment ID if converted

  - `shipmentKey` (string,null)
    Shipment friendly ID if converted

  - `createdAt` (string, required)

  - `updatedAt` (string,null)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 404 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message