Building a Proposal Item by Item

This guide walks through the typical sequence for managing items on a proposal: add the item, price it, assign a supplier, then organize it alongside other items. Each step links to its full endpoint reference in Proposal Items.

The calls that change an item all return the same List<PublicAreaItemModel> response shape. See that page for the shared error codes and flag conventions, and reading proposal items for what the returned fields mean. List item suppliers is the exception — it returns supplier records rather than items.The curl snippets here are trimmed to the payload. Every real request also needs the four HMAC headers from signing requests. The POST calls send a JSON body, so set Content-Type: application/json and sign that same value. The GET has no body, and its canonical message omits the content-type segment entirely.

Add the item

Call add items with the catalog item id, its type, and the target area option. Area option ids come from get proposal, under areas[].options[]. The response includes the new item’s id — save it for every following step.

curl

curl -X POST https://api.portal.io/public/proposals/123/items \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "catalogItemId": 88213,
        "itemType": "Part",
        "proposalAreaOptions": [{ "proposalAreaOptionId": 201, "quantity": 2 }]
      }
    ]
  }'

response

[
  {
    "id": 5001,
    "itemType": "Part",
    "referencedItemId": 88213,
    "shortDescription": "Sonos Amp",
    "sellPrice": 649.00,
    "cost": 499.00,
    "quantity": 2,
    "supplier": "Sonos Inc.",
    "total": { "amount": 1298.00, "currency": { "code": "USD", "symbol": "$" }, "isCombinedPrice": false }
  }
]

Price the item

Adjust the sell price, cost, or MSRP if the catalog defaults don’t apply. Use update sell price, update cost, or update MSRP — each accepts either an absolute value or a percentage + basis.

curl

curl -X POST https://api.portal.io/public/proposals/123/items/5001/sellprice \
  -H 'Content-Type: application/json' \
  -d '{ "sellPrice": 599.00, "setDefault": false, "updateAllInstances": false }'

response

[
  {
    "id": 5001,
    "sellPrice": 599.00,
    "cost": 499.00,
    "quantity": 2,
    "total": { "amount": 1198.00, "currency": { "code": "USD", "symbol": "$" }, "isCombinedPrice": false }
  }
]

Set the supplier

Call list item suppliers to see which suppliers are available for this item, then set item supplier with the chosen supplier’s id. This updates every instance of the same catalog item in the proposal.

curl

curl https://api.portal.io/public/proposals/123/items/5001/suppliers

response

[
  { "id": 771, "name": "Sonos Inc.", "isDefault": true, "isInStock": true },
  { "id": 902, "name": "ADI Global Distribution", "isDefault": false, "isInStock": true }
]

curl

curl -X POST https://api.portal.io/public/proposals/123/items/5001/supplier/902 \
  -H 'Content-Type: application/json' \
  -d '{ "setDefault": false }'

response

[
  {
    "id": 5001,
    "supplier": "ADI Global Distribution",
    "cost": 512.50,
    "sellPrice": 599.00,
    "total": { "amount": 1198.00, "currency": { "code": "USD", "symbol": "$" }, "isCombinedPrice": false }
  }
]

Organize the item

Once pricing and supplier are set, move or copy the item to its final area option with move items or copy items. Nested (child) items move or copy along with their parent unless you suppress that with moveNestedItems/copyNestedItems.

curl

curl -X POST https://api.portal.io/public/proposals/123/items/move \
  -H 'Content-Type: application/json' \
  -d '{ "destinationAreaOptionId": 305, "proposalItemIds": [5001], "moveNestedItems": true }'

response

[
  {
    "id": 5001,
    "shortDescription": "Sonos Amp",
    "supplier": "ADI Global Distribution",
    "sellPrice": 599.00,
    "quantity": 2,
    "total": { "amount": 1198.00, "currency": { "code": "USD", "symbol": "$" }, "isCombinedPrice": false }
  }
]

Next steps

To remove an item instead, see delete items — note its response is void, unlike every step above.
To pull the item’s supplier cost from the catalog after a supplier price change elsewhere, see refresh item costs — also void.
For the tax-exempt and recurring-service flags, see the Flags endpoints.
No webhook fires when an item changes, so to pick up edits made elsewhere, re-fetch get proposal and watch its Last-Modified header.

Get Started

Authentication

Concepts

Building a Proposal Item by Item

Next steps

​Next steps

Next steps