> ## Documentation Index > Fetch the complete documentation index at: https://docs.cargado.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a bid > Patch a Bid. Omitted fields are left unchanged; sending null explicitly clears the field. Currently only `externalId` is patchable. Returns the updated bid. ## OpenAPI ````yaml /openapi.yml post /bids/update openapi: 3.1.0 info: title: Cargado API version: 1.0.0 description: Cargado's API termsOfService: https://cargado.com/terms/ contact: email: dev-support@cargado.com servers: - url: https://api.cargado.com description: The production Cargado API server security: [] tags: - name: Border Crossings - name: Loads - name: Rates - name: CarrierRelationship - name: User - name: Team - name: Webhooks - name: Bids paths: /bids/update: post: tags: - Bids summary: Update a bid description: |- Patch a Bid. Omitted fields are left unchanged; sending null explicitly clears the field. Currently only `externalId` is patchable. Returns the updated bid. operationId: UpdateBid parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateBidInput' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/Bid' '401': description: Unauthorized content: application/json: schema: properties: message: type: string required: - message type: object examples: Example 1: value: message: Unauthorized '404': description: Not Found content: application/json: schema: properties: message: type: string required: - message type: object examples: Example 1: value: message: Bid with ID bid_… not found security: - apiKey: [] components: schemas: UpdateBidInput: description: |- Patch a Bid. Omitted fields are left unchanged; sending a field with `null` explicitly clears it; sending a value sets it. properties: bidId: type: string description: The id of the Bid to update. minLength: 1 maxLength: 64 externalId: type: - string - 'null' description: |- The id of the bid in the integration's TMS. Send a string to set, `null` to clear, or omit to leave unchanged. minLength: 1 maxLength: 255 required: - bidId type: object additionalProperties: true Bid: properties: id: type: string description: 'Cargado-issued identifier for this bid (prefix: `bid_`).' status: $ref: '#/components/schemas/BidStatus' externalId: type: - string - 'null' description: >- The unique id for this bid/offer object in your TMS. This identifier will not be displayed outside your organization. Examples: "456293", "TMS232423" minLength: 1 maxLength: 255 examples: - '456293' rateDetails: $ref: '#/components/schemas/BidRateDetails' description: Pricing details for this bid, broken out by line item. loadsPerPeriod: type: - number - 'null' format: double description: |- The number of loads the carrier is able to cover at this rate during the lane period. Null for single-load bids; populated for lane bids. minimum: 0 createdAt: type: string description: The time the bid was created, as an ISO-8601 timestamp. format: date-time updatedAt: type: string description: The time the bid was last updated, as an ISO-8601 timestamp. format: date-time counterBid: allOf: - $ref: '#/components/schemas/CounterBid' nullable: true description: |- The current active counter on this bid, if any. Null when no counter is in progress (or when the bid has never been countered). required: - id - status - externalId - rateDetails - loadsPerPeriod - createdAt - updatedAt - counterBid type: object additionalProperties: true BidStatus: type: string enum: - ACTIVE - ACCEPTED - REJECTED - REVOKED - COUNTERED - COUNTER_ACCEPTED - CLOSED description: |- The lifecycle status of a bid. - `ACTIVE` — the bid is live and awaiting a response from the broker. - `ACCEPTED` — the bid has been accepted by the broker. - `REJECTED` — the bid has been rejected by the broker. - `REVOKED` — the carrier withdrew the bid before a response. - `COUNTERED` — the broker has issued a counter on this bid. - `COUNTER_ACCEPTED` — a counter on this bid was accepted; the bid is settled at the countered rate. - `CLOSED` — the bid is no longer actionable (for example, the posting ended or another bid was accepted). BidRateDetails: $ref: '#/components/schemas/ItemizedBid' description: |- Pricing details for a bid. Always an itemized breakdown — even a single all-in price is delivered as one line item, so future pricing shapes can be added without breaking integrations. CounterBid: properties: id: type: string description: 'Cargado-issued identifier for this counter (prefix: `cb_`).' status: $ref: '#/components/schemas/CounterBidStatus' rateDetails: $ref: '#/components/schemas/CounterBidRateDetails' description: Pricing details for this counter, broken out by line item. createdAt: type: string description: The time the counter was created, as an ISO-8601 timestamp. format: date-time required: - id - status - rateDetails - createdAt type: object additionalProperties: true ItemizedBid: description: |- An itemized pricing breakdown for a bid. `totalAmount` is the sum the carrier is offering; `lineItems` shows how that total breaks down (an all-in price, per-country legs, border crossings, etc.). properties: type: type: - string - 'null' enum: - ItemizedBid totalAmount: $ref: '#/components/schemas/CurrencyValue' description: The total price offered for this bid, in the bid's currency. lineItems: items: $ref: '#/components/schemas/BidLineItem' type: array description: The pricing components that make up `totalAmount`. required: - type - totalAmount - lineItems type: object additionalProperties: true CounterBidStatus: type: string enum: - ACTIVE - ACCEPTED - REJECTED - REVOKED - CLOSED description: >- The lifecycle status of a counter bid. - `ACTIVE` — the counter is live and awaiting a response from the carrier. - `ACCEPTED` — the counter has been accepted by the carrier. - `REJECTED` — the counter has been rejected by the carrier. - `REVOKED` — the counter was withdrawn before a response. - `CLOSED` — the counter is no longer actionable (for example, a newer counter superseded it). CounterBidRateDetails: $ref: '#/components/schemas/SimpleCounterBid' description: |- Pricing details for a counter bid. Currently always a single total amount; itemized counters may be added in the future, so this is shaped as a discriminated union from day one. CurrencyValue: description: >- An object representing a monetary value in a given currency. Amount is in the lowest denomination of the currency (e.g. cents). For example, $15.25 is represented as `{ currencyCode: 'USD', amount: 1525 }`. properties: currencyCode: $ref: '#/components/schemas/CurrencyCode' description: The currency code of the amount amount: type: integer format: int32 description: >- The currency amount in the lowest denomination of the currency (e.g. cents) minimum: 0 maximum: 1000000000 required: - currencyCode - amount type: object additionalProperties: true BidLineItem: anyOf: - $ref: '#/components/schemas/AllInBidLineItem' - $ref: '#/components/schemas/CountryLegBidLineItem' - $ref: '#/components/schemas/BorderCrossingBidLineItem' description: |- A single component of a bid's itemized pricing. Discriminated by `type`: `AllIn` for a single total, `CountryLeg` for per-country leg pricing on cross-border moves, and `BorderCrossing` for the fee charged at a specific border crossing. SimpleCounterBid: description: |- A counter bid expressed as a single total amount (no line-item breakdown). properties: type: type: - string - 'null' enum: - SimpleCounterBid totalAmount: $ref: '#/components/schemas/CurrencyValue' description: The total counter amount being offered. required: - type - totalAmount type: object additionalProperties: true CurrencyCode: type: string enum: - USD - MXN - CAD description: Supported currency codes for monetary values. AllInBidLineItem: description: |- A single all-in price for the entire move. Used when the carrier is offering one flat rate rather than itemizing by leg or fee. properties: type: type: - string - 'null' enum: - AllIn totalAmount: $ref: '#/components/schemas/CurrencyValue' description: The total amount being offered for the move. required: - type - totalAmount type: object additionalProperties: true CountryLegBidLineItem: description: |- The pricing for one country's portion of a cross-border move. Use this when the bid is broken out by which country the freight is moving in (for example, a US leg priced separately from a Mexico leg). properties: type: type: - string - 'null' enum: - CountryLeg legCountry: $ref: '#/components/schemas/CountryCode' description: The country this leg is in. legApproximateDistanceMiles: type: number format: double description: Approximate distance covered in this country's portion of the move. rate: anyOf: - properties: currencyValue: $ref: '#/components/schemas/CurrencyValue' type: type: - string - 'null' enum: - FIXED_AMOUNT required: - currencyValue - type type: object - properties: distanceUnit: $ref: '#/components/schemas/LargeDistanceUnit' currencyValue: $ref: '#/components/schemas/CurrencyValue' type: type: - string - 'null' enum: - RATE_PER_DISTANCE required: - distanceUnit - currencyValue - type type: object description: >- How this leg is priced — either a single fixed amount, or a per-distance rate paired with a distance unit. totalAmount: $ref: '#/components/schemas/CurrencyValue' description: The total amount for this leg in the bid's currency. required: - type - legCountry - legApproximateDistanceMiles - rate - totalAmount type: object additionalProperties: true BorderCrossingBidLineItem: description: |- The pricing for the border-crossing portion of a cross-border move (for example, the fee for crossing through a specific US/MX port). properties: type: type: - string - 'null' enum: - BorderCrossing legOriginCountry: $ref: '#/components/schemas/CountryCode' description: The country the freight is leaving. legDestinationCountry: $ref: '#/components/schemas/CountryCode' description: The country the freight is entering. legPort: $ref: '#/components/schemas/UsMxBorderCrossing' description: The specific border crossing used for this leg. totalAmount: $ref: '#/components/schemas/CurrencyValue' description: >- The total amount being charged for the crossing, in the bid's currency. required: - type - legOriginCountry - legDestinationCountry - legPort - totalAmount type: object additionalProperties: true CountryCode: type: string enum: - US - MX - CA description: The ISO 3166-1 alpha-2 country code of the place. LargeDistanceUnit: type: string enum: - MI - KM UsMxBorderCrossing: type: string enum: - LAREDO_INTL_BRIDGE - LAREDO_COLUMBIA - BROWNSVILLE - CALEXICO_EAST - DEL_RIO - DOUGLAS - EAGLE_PASS - EL_PASO - HIDALGO - NOGALES - OTAY_MESA - SAN_LUIS - TECATE securitySchemes: apiKey: type: apiKey in: header name: api-key ````