Bid

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/buildworkpro-com/json-schema/buildworkpro-com-bid-schema.json",
  "title": "Bid",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/buildworkpro-com-openapi.json#/components/schemas/Bid",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "bidNumber": {
      "type": "string"
    },
    "contactId": {
      "type": [
        "integer",
        "null"
      ]
    },
    "leadId": {
      "type": [
        "integer",
        "null"
      ]
    },
    "projectId": {
      "type": [
        "integer",
        "null"
      ]
    },
    "status": {
      "type": "string"
    },
    "subtotal": {
      "type": [
        "string",
        "null"
      ]
    },
    "taxAmount": {
      "type": [
        "string",
        "null"
      ]
    },
    "total": {
      "type": [
        "string",
        "null"
      ]
    },
    "lineItems": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/BidLineItem"
      },
      "description": "Present on GET /bids/{id}. unitPrice and total are pre-markup cost; customerUnitPrice and customerTotal are the customer-facing prices. Omitted from list responses."
    },
    "discountAmount": {
      "type": [
        "string",
        "null"
      ]
    },
    "taxRate": {
      "type": [
        "string",
        "null"
      ]
    },
    "discount": {
      "type": [
        "string",
        "null"
      ]
    },
    "discountType": {
      "type": [
        "string",
        "null"
      ]
    },
    "validUntil": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "notes": {
      "type": [
        "string",
        "null"
      ]
    },
    "terms": {
      "type": [
        "string",
        "null"
      ]
    },
    "siteAddress": {
      "type": [
        "string",
        "null"
      ]
    },
    "siteCity": {
      "type": [
        "string",
        "null"
      ]
    },
    "siteState": {
      "type": [
        "string",
        "null"
      ]
    },
    "siteZipCode": {
      "type": [
        "string",
        "null"
      ]
    },
    "sentAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "acceptedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "acceptedBy": {
      "type": [
        "string",
        "null"
      ]
    },
    "createdAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "string"
        }
      ]
    },
    "updatedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "string"
        }
      ]
    },
    "isPractice": {
      "type": "boolean",
      "description": "Read-only. Present on GET /bids/{id}. True for the onboarding practice bid a user sends to themselves; it becomes a normal bid (false) once it is sent to anyone outside the organization."
    },
    "proposalDetail": {
      "type": "string",
      "enum": [
        "total",
        "line_items",
        "full"
      ],
      "description": "What the customer sees: total (a scope paragraph and the totals, no line table), line_items (the line table, no sub-lines) or full (the line table with each line's sub-lines)."
    },
    "proposalShowQuantities": {
      "type": "boolean",
      "description": "Whether the proposal prints the Qty column."
    },
    "proposalShowUnitPrices": {
      "type": "boolean",
      "description": "Whether the proposal prints the Unit price column."
    },
    "showSublines": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Deprecated alias for proposalDetail. true maps to full; false maps to line_items, except a bid already at total stays total. Ignored when proposalDetail is sent. Responses derive this as proposalDetail === full.",
      "deprecated": true
    }
  },
  "required": [
    "id",
    "bidNumber",
    "contactId",
    "leadId",
    "projectId",
    "status",
    "subtotal",
    "taxAmount",
    "total",
    "taxRate",
    "discount",
    "discountType",
    "validUntil",
    "notes",
    "terms",
    "siteAddress",
    "sentAt",
    "acceptedAt",
    "acceptedBy",
    "createdAt",
    "updatedAt",
    "proposalDetail",
    "proposalShowQuantities",
    "proposalShowUnitPrices"
  ],
  "$defs": {
    "BidLineItem": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "bidId": {
          "type": "integer"
        },
        "kind": {
          "type": "string",
          "enum": [
            "item",
            "section",
            "note"
          ],
          "description": "item = priced line; section = header grouping the rows after it; note = customer-visible text."
        },
        "isOptional": {
          "type": "boolean",
          "description": "An optional (alternate) priced line, quoted outside the bid total."
        },
        "markName": {
          "type": [
            "string",
            "null"
          ],
          "description": "Human-friendly mark name, e.g. W-01. Null on section and note rows."
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "quantity": {
          "type": [
            "string",
            "null"
          ],
          "description": "Quantity. Sections and notes are not priced."
        },
        "unitPrice": {
          "type": [
            "string",
            "null"
          ],
          "description": "Pre-markup direct cost per unit (before margin, overhead, commission, and distributed project costs). Not the customer price — use customerUnitPrice."
        },
        "total": {
          "type": [
            "string",
            "null"
          ],
          "description": "Pre-markup line cost. Summing these does not equal the bid subtotal. Use customerTotal."
        },
        "customerUnitPrice": {
          "type": [
            "string",
            "null"
          ],
          "description": "Customer-facing unit price after markup and this line's share of distributed costs. Null on section and note rows. An optional line is priced on its own and is excluded from the bid subtotal."
        },
        "customerTotal": {
          "type": [
            "string",
            "null"
          ],
          "description": "Customer-facing line total in dollars, reconciled to the cent. Null on section and note rows. The sum over priced, non-optional lines equals the bid's pre-discount subtotal."
        },
        "sellTaxPercent": {
          "type": [
            "string",
            "null"
          ],
          "description": "Per-line sales-tax rate (0–100). Null inherits the bid's tax rate; 0 exempts the line."
        },
        "buyTaxPercent": {
          "type": [
            "string",
            "null"
          ],
          "description": "Per-line purchase-tax rate (0–100) on a flat line's cost. Null inherits the product's rate."
        },
        "order": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Sort position within the bid. A section covers every following row until the next section."
        }
      },
      "required": [
        "id",
        "bidId",
        "kind",
        "isOptional",
        "markName",
        "description",
        "quantity",
        "unitPrice",
        "total",
        "customerUnitPrice",
        "customerTotal",
        "sellTaxPercent",
        "buyTaxPercent",
        "order"
      ]
    }
  }
}