Skip to main content
When work needs pricing before it proceeds, suppliers submit proposals (quotes) against the work order. Through the Buyer API, proposals are read-only: you list them, inspect line items, and reconcile them against invoices. Approving or declining a proposal happens in the OpenWrench app. All examples assume:

Proposal statuses

Statuses persist lowercase.

Reading proposals

Scoping rules worth knowing:
  • Suppliers’ unsubmitted drafts are always excluded from lists.
  • If your API key’s contact is location-restricted, you only see proposals for accessible locations. A contact with an empty accessible set gets an empty page, not an error.
  • The single read returns 404 for soft-deleted proposals, drafts, and proposals outside your location scope. Treat 404 as “not visible to you”, not necessarily “does not exist”.

Filter reference

The list takes offset, limit (default 10, max 25), sort_by, and order, plus the filters below. Filters combine with AND, and always combine with your key’s tenant and location scoping. There is no count endpoint: the list response’s count is the total number of matches, so request limit=1 when you only need the number.
Value rules:
  • Sorting. sort_by supports createdAt, updatedAt, totalAfterTax, id, workOrderId, locationId, supplierFacilityId, and buyerFacilityId. With no sort_by, or any other value, results are sorted by id ascending (oldest first). Once you set sort_by, order defaults to asc, so send order=desc for newest first.
  • Lists take commas with no spaces. A singular key (status) takes one value; the plural key takes a comma-separated list. A space after a comma can fail the request.
  • Dates use MM/dd/yyyy HH:mm:ss, for example 08/01/2026 00:00:00. The value is a local wall-clock time, read in the zone you pass in timezone, or in UTC without it. The time is required. The start bound is inclusive at the time you send. The end bound covers the whole end day in that zone: OpenWrench replaces its time with 23:59:59. URL-encode the value. Don’t add an offset such as -05:00 to the value: OpenWrench ignores it.
  • A date that doesn’t parse returns 400 with Invalid <key>. Expected format MM/dd/yyyy HH:mm:ss. That includes ISO 8601 values (2026-10-09T00:00:00), dates without a time (10/09/2026), and values of only spaces. OpenWrench still reads an empty value as 1 January 1970.
  • timezone takes an IANA zone name, such as America/Chicago or UTC. Fixed offsets (-05:00, GMT-5), abbreviations (CST), and unknown names return 400. See Date formats for daylight saving time.
  • Values must be well formed. A non-numeric id, or a boolean other than true or false, can fail the request with a 500 rather than a 400.
  • Unrecognized filters are ignored, and tenant scoping can’t be overridden: buyerCompanyId is always set from your API key, and drafts are excluded even if you ask for status=draft.
To match one local day, send the same date for both bounds along with your zone. This request returns proposals awarded on October 9, 2026, Central time:

Inside a proposal

The money is broken into the same sections as invoices: laborLineItems, materialLineItems, travelLineItems, freightLineItems, and miscLineItems. Each section has its own tax rate and ...TotalBeforeTax, and the sections roll up to totalBeforeTax, tax, and totalAfterTax. Monetary values serialize as strings; parse them as decimals, not floats, if you are doing arithmetic. Other useful fields: workOrderId, supplierFacilityId, workOrderNTEBeforeApproval (the work order’s not-to-exceed at submission time), proposalPdfLink, attachments, submittedAt, and approvedAt.

Where proposals fit the flow

  1. The supplier submits a proposal; the work order typically pauses awaiting approval.
  2. Your approvers award or decline it in the app. Award raises the effective spend ceiling for the job.
  3. When the final invoice arrives, compare invoiceTotalAfterTax against the awarded proposal’s totalAfterTax before approving payment. Flag variances above your tolerance for human review.
A practical polling loop for a procurement dashboard: filter status=pending, sort with sort_by=createdAt&order=desc, and page with limit=25, respecting the rate limit of 10 requests per 20-second window.