--- title: "[beta] Update a maintenance estimate" method: PATCH path: "/maintenance/estimates" tags: ["Beta APIs"] --- # \[beta\] Update a maintenance estimate `PATCH /maintenance/estimates` ## Request - Base URL: `https://api.samsara.com` - URL: `https://api.samsara.com/maintenance/estimates` - Auth: HTTP bearer Update eligible quote content or convert the active selected expectedCost recommendation to vendorQuote with the same estimate ID. Type conversion can include pricing changes but must be separate from approval, cancellation and award; reverse conversion is not allowed. Otherwise approve or deny through Samsara approval and UTS, or separately award an approved quote through the native work-order flow. Award assigns the vendor and preserves the exact financial baseline; applying quote lines to work-order service tasks is a separate dashboard action. Selecting a different quote while an active award exists is rejected; withdraw an eligible awarded quote before awarding its replacement. Approval and award require their respective authority and must be separate updates. Approval, cancellation or award cannot be combined with content or external ID changes. Cancel an unapproved or pending estimate and close any open approval ticket. Cancellation retains history. For an active externally selected recommendation or unapproved quote, this existing cancellation path also releases that selection, clears its vendor assignment and returns an open work order to vendor selection. Cancelling an unselected recommendation leaves other selections unchanged, and native quote cancellation preserves vendor assignment. A current finished vendorQuote that is approved, denied or awarded can instead be withdrawn while retaining its approval decision and award history and retiring only its exact completed active award. This decided-quote withdrawal does not change the work order, vendor assignment, selection attempt, service tasks, actual costs or invoices. It is not restricted by whether repair work has started. Cancellation requires approval authority and, for a known or current award, separate award authority. Processing or superseded quotes and incomplete awards cannot be withdrawn; retry an award in progress after reconciliation. Repeating a cancellation is safe. Omitted fields remain unchanged. Rate limit: 100 requests/min (learn more about rate limits here). To use this endpoint, select **Write Work Orders** under the Work Orders category when creating or editing an API token. Learn More. **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team. ## Query parameters - `includeExternalIds` boolean - `id` string, required ## Request body - MaintenanceEstimatesPatchMaintenanceEstimateRequestBody: Omitted fields remain unchanged. Priced content is frozen after decision. No public optimistic-concurrency parameter is required. - `approvalStatus` 'approved' | 'denied' | 'cancelled': Approve or deny the current quote through Samsara approval and UTS. Cancel an unapproved or pending estimate and close any open approval ticket. For an active externally selected recommendation or unapproved quote, this existing cancellation path also releases that selection, clears its vendor assignment and returns an open work order to vendor selection. Unselected recommendations leave other selections unchanged, and native quote cancellation preserves vendor assignment. A current finished vendorQuote that is approved, denied or awarded can instead be withdrawn while retaining its approval decision and award history and retiring only its exact completed active award. This decided-quote withdrawal does not change the work order, vendor assignment, selection attempt, service tasks, actual costs or invoices. It is not restricted by whether repair work has started. Cancellation requires approval authority and, for a known or current award, separate award authority. Processing or superseded quotes and incomplete awards cannot be withdrawn; retry an award in progress after reconciliation. Repeating a cancellation is safe. Omit to preserve the current status. Send approval or cancellation separately from content changes, estimateType and isAwarded. Valid values: `approved`, `denied`, `cancelled` - `estimateType` 'expectedCost' | 'vendorQuote': Omit to preserve the type. Repeating the current type is allowed. Only the active selected expectedCost recommendation can become a vendorQuote, preserving its estimate ID. The reverse transition is not allowed. Type conversion can include pricing changes, but must be separate from approval, cancellation and award. Valid values: `expectedCost`, `vendorQuote` - `externalIds` object: Estimate external identifiers. Responses include these only when includeExternalIds=true; default omitted. - `externalRequest` MaintenanceEstimateExternalRequestInputRequestBody: Optional provider metadata. Every child is optional. PATCH replaces the whole object, null or an empty object clears it, and omission preserves it. Nonempty provider metadata requires an actual quote or an active selected recommendation. - `actionUrl` string: Optional provider URL. Nonempty values must be HTTPS without embedded credentials, at most 2048 bytes; empty strings are accepted. - `externalRequestId` string: Optional provider request reference, not an estimate alias or idempotency key. Empty strings are accepted. - `externalSystem` string: Optional external provider name; empty strings are accepted. - `message` string: Optional display message; empty strings are accepted. - `isAwarded` boolean: Only true is writable: award an eligible approved quote, assign its vendor to the work order and preserve its financial baseline. Applying quote lines to work-order service tasks is a separate dashboard action. A different quote cannot replace an active award through this API; withdraw an eligible awarded quote before awarding its replacement. Send award separately from content and external ID changes. Defaults to unchanged when omitted; requires separate award authority. - `lineItems` MaintenanceEstimateLineInputRequestBody[]: Complete set of 1 to 200 priced lines when supplied. - `amount` MaintenanceEstimateMoneyRequestBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `costType` 'labor' | 'parts': Optional classification of the entire line. Labor assigns all cost to labor; parts assigns all cost to parts. Omission leaves a new or replacement line unclassified; it does not infer a type from description. Valid values: `labor`, `parts` - `description` string: Vendor's quote text, at most 2000 Unicode characters. - `id` string: Existing line ID when retaining a line during PATCH. - `quantity` number: Quantity or labor hours, greater than zero with at most two fractional digits. When supplied, unitRate is also required. Omitted when actual quantity is unknown. - `serviceTaskId` string: Associated service-task instance belonging to this WO. - `unitRate` MaintenanceEstimateUnitRateRequestBody: Price per quantity unit in the organization's currency. Rates can include fractional cents; round the extended line amount once to cents. - `amount` string, required: Nonnegative decimal unit price, with up to six fractional digits. Signs, exponents and grouping separators are not accepted. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: Three-letter ISO 4217 currency code. Must match the organization's current currency and the line amount. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `notes` string: Notes, at most 4000 Unicode characters. PATCH null clears. - `quotedAtTime` string, date-time: Actual quote timestamp. Omit if the source only has a date; do not invent a time or offset. PATCH null clears. - `tax` MaintenanceEstimateMoneyRequestBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` ## Response `200` OK response. - MaintenanceEstimatesPatchMaintenanceEstimateResponseBody - `data` MaintenanceEstimateObjectResponseBody, required: A priced vendor recommendation or quote for one work order. - `approvalSource` 'unknown' | 'none' | 'policy' | 'samsara', required: Authority for the current approval state. Defaults to none. Valid values: `unknown`, `none`, `policy`, `samsara` - `approvalStatus` 'unknown' | 'unapproved' | 'pending' | 'approved' | 'denied' | 'cancelled', required: Approval state. Vendor quotes default to unapproved; expectedCost recommendations report unknown until conversion, or cancelled after cancellation. Approval and award are separate operations. Valid values: `unknown`, `unapproved`, `pending`, `approved`, `denied`, `cancelled` - `attachments` MaintenanceEstimateAttachmentResponseBody[], required: Quote documents. API additions enforce a 50-file WO admission limit against observed files and pending API reservations. - `createdAtTime` string, date-time, required: Time the attachment was created. - `id` string, required: Stable attachment ID. - `name` string, required: Original or generated filename. - `processingStatus` 'unknown' | 'processing' | 'finished', required: Attachment availability. Defaults to processing until a validated download is available; unknown when availability cannot be determined. Valid values: `unknown`, `processing`, `finished` - `updatedAtTime` string, date-time, required: Latest attachment change; initially equal to creation time. - `url` string, uri: Temporary download URL; present only when processingStatus is finished. - `urlExpiresAt` string, date-time: Expiration of the temporary download URL; present only with url. - `createdAtTime` string, date-time, required: Server creation time. - `estimateType` 'unknown' | 'expectedCost' | 'vendorQuote', required: Whether this estimate is a recommendation or a vendor quote. Omitted create values default to vendorQuote. Unknown represents an unrecognized type. Valid values: `unknown`, `expectedCost`, `vendorQuote` - `externalIds` object: Estimate external identifiers. Responses include these only when includeExternalIds=true; default omitted. - `externalRequest` MaintenanceEstimateExternalRequestResponseBody: Provider request details. This metadata does not create a request or change approval or award status. - `actionUrl` string, uri: HTTPS provider URL without embedded credentials; at most 2048 bytes. - `externalRequestId` string: Provider request reference, not an estimate lookup alias or idempotency key; at most 200 characters. - `externalSystem` string: External provider name; at most 100 characters. - `message` string: Optional display message; at most 500 characters. - `id` string, required: Stable estimate ID. - `isAwarded` boolean, required: Whether this exact vendor quote has been awarded for the WO. Defaults to false; recommendation selection and approval do not award. - `lineItems` MaintenanceEstimateLineItemResponseBody[], required: Up to 200 priced lines; incomplete dashboard quotes may have no lines. - `amount` MaintenanceEstimateMoneyResponseBody, required: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `costType` 'unknown' | 'labor' | 'parts': Whether the entire line is labor or parts. Omitted when classification is absent or mixed; unknown represents an unrecognized classification. No classification is inferred from description. Valid values: `unknown`, `labor`, `parts` - `description` string: Vendor quote text; retained even when serviceTaskId is supplied. Maximum 2000 Unicode characters. - `id` string, required: Server-generated line ID. - `quantity` number: Quantity or labor hours, greater than zero with at most two fractional digits. When supplied, unitRate is also required. Omitted when actual quantity is unknown. - `serviceTaskId` string: Associated WO service-task instance ID; not a task catalog ID. - `unitRate` MaintenanceEstimateUnitRateResponseBody: Price per quantity unit in the organization's currency. Rates can include fractional cents; round the extended line amount once to cents. - `amount` string, required: Nonnegative decimal unit price, with up to six fractional digits. Signs, exponents and grouping separators are not accepted. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: Three-letter ISO 4217 currency code. Must match the organization's current currency and the line amount. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `notes` string: Additional notes, at most 4000 Unicode characters. - `quotedAtTime` string, date-time: Actual instant the vendor issued the quote; omit when only a date is known. - `subtotal` MaintenanceEstimateMoneyResponseBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `supersededByEstimateId` string: Successor estimate; a superseded quote is historical. - `supersedesEstimateId` string: Previous denied estimate replaced by this new quote. - `tax` MaintenanceEstimateMoneyResponseBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `total` MaintenanceEstimateMoneyResponseBody: Nonnegative amount in the organization's currency. Supported currencies: usd, gbp, cad, eur, chf, mxn. Exact decimal strings are required. - `amount` string, required: The money amount. - `currency` 'usd' | 'gbp' | 'cad' | 'eur' | 'chf' | 'mxn', required: The currency of money. This is a 3-letter ISO 4217 currency code. Valid values: `usd`, `gbp`, `cad`, `eur`, `chf`, `mxn` - `updatedAtTime` string, date-time, required: Latest public content or lifecycle change. - `vendorId` string: Vendor location ID. Resolve the location via GET /fleet/maintenance/vendor-locations. - `version` integer, required: Monotonic change counter including lifecycle and attachment updates. - `workOrderId` string, required: Owning numeric work order ID. ## Other responses - `401`: Unauthorized response. - `404`: Not Found response. - `405`: Method Not Allowed response. - `409`: Conflict response. - `413`: Content Too Large response. - `429`: Too Many Requests response. - `500`: Internal Server Error response. - `501`: Not Implemented response. - `502`: Bad Gateway response. - `503`: Service Unavailable response. - `504`: Gateway Timeout response. - `default`: Bad Request response. --- [API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)