Bids and bid pricing

A bid is a tender your organization has decided to work on, and it moves through stages from review to won or lost. An item price is the unit price your organization sets for one of the tender's items. Everything that prepares a bid reads these prices afterwards (quotations, the NUPCO files and the cover letter), so these tools are where a bid's prices are written.

The bid pipeline

One bid per tender. The stages in order are reviewing, preparing and submitted, ending in one of won, lost or cancelled.

bids_list

Lists your organization's bids, each with its tender. Use it to see what you are working on and at which stage, and filter by stage when you need to.

Read-only · scope bids.read · all roles · Pro and Enterprise plans

Returns: A page of bids, each with its tender, and the total count.

• The technical and viewer (no pricing) roles see the bids, but bid_amount comes back empty for them.

bids_create

Adds a tender to your organization's bids. A tender has one bid only, so the tool answers with a conflict when one already exists.

Changes data · scope bids.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "tender_id": 48213,
  "status": "reviewing",
  "notes": "Syringes lot, check MDMA status first"
}

Returns: The bid that was created.

• Each new bid counts against your plan's limit on active tenders, and the tool refuses once it is reached.

bids_update

Changes a bid's stage, amount or notes. Only what you send changes.

Changes data · scope bids.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "id": 311,
  "status": "submitted",
  "bid_amount": 148167.95
}

Returns: The bid after the change.

• Changing the stage fires the bid.status_changed event to your organization's webhooks.

bids_delete

Removes a bid from your organization's list. This cannot be undone; the item prices are kept.

Deletes or overwrites data · scope bids.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: A confirmation of the deletion.

Item prices

Each tender item has one price for your organization. Adding and changing use the same tool, and a tender needs no bid before you price its items.

bid_pricing_list

Lists your organization's prices for one tender's items, with the award outcome recorded for each.

Read-only · scope bids.read · roles: owner, admin, sales, purchasing, viewer · Pro and Enterprise plans

Returns: The item prices, each with the ID that the outcome and delete tools take.

bid_pricing_set_batch

Prices one item, or up to 500 items of one tender, in a single call, from prices you have typed in or from a margin on the cost of each item's selected product. Your organization keeps one price per item, and a call replaces the previous one.

Changes data · scope bids.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "tender_id": 48213,
  "items": [
    {
      "tender_item_id": 902114,
      "unit_price": 3.45
    },
    {
      "tender_item_id": 902115,
      "unit_price": 12.9,
      "notes": "Includes delivery"
    },
    {
      "tender_item_id": 902116,
      "margin_percent": 20
    }
  ]
}

Returns: A list of what was priced and a list of what failed, with a count of each.

• Rows are handled one by one: a row whose item is not a live item of the tender fails alone with a readable error, and the rest are saved.
• An item ID repeated in the call rejects the whole call before anything is saved.
• With margin_percent the price is built on the cost price of the item's selected product (dollars at the fixed 3.75 rate) converted to one unit of the item, rounded to four decimals, and only the price is saved: a margin of 20 on a 100 SAR cost gives 125 SAR. The cost is stated per the product's price_basis, so an item bought per box of 100 is built on the cost of a box, and an item whose unit is unsure on the cost of one unit of the product. The reply adds margin_percent, cost_sar (per unit of the item), product_id, price_level, level_count, level_measure and level_status (check means the unit is unsure, with a suggestion) to the priced row. This pricing is for the owner, admin and purchasing roles, since the resulting price gives the cost away, and the sales role is refused.
• A margin row fails alone with the cause in reason: no_selection when the item has no selected product (select one with `tender_item_product_selection_set`), archived_product when the selected product is archived, no_cost when the product has no cost price above zero (add one with `products_update`), no_conversion when the cost cannot be converted to the item's unit because a packing count is missing, with missing naming it (fill it with products_update, or set the item's unit with `tender_item_price_levels_set`), and rounds_to_zero when the price rounds to 0.0000. A margin row takes no notes and leaves the item's note as it was.
• A positive price marks the item as participating, and a price of 0 keeps the price row and removes that mark; the reply says for each row which happened. To mark it again use `tender_item_participation_set_batch`. For prices that arrive in an Excel or CSV file, use `sheet_import` with the bid_pricing target, which reads every row on the server.

bid_pricing_outcome_set

Records whether a priced item was awarded to your organization (awarded) or not (not_awarded). Send null to put it back to pending.

Changes data · scope bids.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "id": 5521,
  "outcome": "awarded"
}

Returns: The item price with its outcome recorded.

bid_pricing_delete

Removes one item price. This cannot be undone; the participation mark stays as it is.

Deletes or overwrites data · scope bids.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: A confirmation of the deletion.