Update Proposal Item Supplier Cost

curl --request POST \
  --url https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/cost \
  --header 'Accept: <accept>' \
  --header 'Content-Type: application/json' \
  --header 'X-MSS-API-APPID: <api-key>' \
  --header 'X-MSS-API-USERKEY: <api-key>' \
  --header 'X-MSS-CUSTOM-DATE: <api-key>' \
  --header 'X-MSS-SIGNATURE: <api-key>' \
  --data '
{
  "cost": 759.6,
  "costPercentage": 63.6,
  "costPercentageBasis": "PartTotal",
  "setDefault": false,
  "updateAllInstances": false
}
'

import requests

url = "https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/cost"

payload = {
    "cost": 759.6,
    "costPercentage": 63.6,
    "costPercentageBasis": "PartTotal",
    "setDefault": False,
    "updateAllInstances": False
}
headers = {
    "Accept": "<accept>",
    "X-MSS-API-APPID": "<api-key>",
    "X-MSS-API-USERKEY": "<api-key>",
    "X-MSS-CUSTOM-DATE": "<api-key>",
    "X-MSS-SIGNATURE": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Accept: '<accept>',
    'X-MSS-API-APPID': '<api-key>',
    'X-MSS-API-USERKEY': '<api-key>',
    'X-MSS-CUSTOM-DATE': '<api-key>',
    'X-MSS-SIGNATURE': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cost: 759.6,
    costPercentage: 63.6,
    costPercentageBasis: 'PartTotal',
    setDefault: false,
    updateAllInstances: false
  })
};

fetch('https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/cost', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "id": 81376,
    "parentId": 42344,
    "itemType": "Part",
    "referencedItemId": 63140,
    "createdDate": "2030-08-21T00:22:19Z",
    "lastModifiedDate": "2031-02-06T00:22:19Z",
    "brand": "Sonos",
    "model": "Amp",
    "name": "Installation Labor",
    "shortDescription": "Sonos Amp",
    "clientNote": "Mounted in the rack behind the display.",
    "imageUrl": "https://images.portal.io/catalog/sonos-amp.jpg",
    "msrp": 901.23,
    "sellPrice": 583.78,
    "cost": 759.6,
    "costUpdateDate": "2030-11-10T00:22:19Z",
    "supplier": "Sonos Inc.",
    "quantity": 9.6,
    "total": {
      "amount": 982.49,
      "currency": {
        "code": "USD",
        "symbol": "$"
      },
      "isCombinedPrice": false
    },
    "isTaxExempt": false,
    "isRecurringService": false,
    "linkedOrders": [
      {
        "orderId": 21802,
        "orderNumber": 182,
        "orderNumberSuffix": "A",
        "supplier": "Sonos Inc.",
        "supplierRef": "SN-10420",
        "orderName": "Living Room Sonos Amp",
        "orderStatus": "Submitted"
      }
    ]
  }
]

{
  "responseStatus": {
    "errorCode": "BadRequest",
    "message": "Neither an absolute cost nor a percentage was supplied, both were supplied, or a percentage was supplied without its basis."
  }
}

{
  "responseStatus": {
    "errorCode": "Unauthorized",
    "message": "Not Authorized. Ensure a valid session cookie or HMAC authentication headers are provided."
  }
}

{
  "responseStatus": {
    "errorCode": "PaymentRequired",
    "message": "The dealer's subscription is inactive or expired. An active subscription is required to use this endpoint."
  }
}

{
  "responseStatus": {
    "errorCode": "Forbidden",
    "message": "You do not have permission for this action."
  }
}

{
  "responseStatus": {
    "errorCode": "NotFound",
    "message": "Proposal or proposal item not found."
  }
}

{
  "responseStatus": {
    "errorCode": "Conflict",
    "message": "Proposal is in a state that does not allow editing."
  }
}

POST

public

proposals

{ProposalId}

items

{ProposalItemId}

cost

Update Proposal Item Supplier Cost

curl --request POST \
  --url https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/cost \
  --header 'Accept: <accept>' \
  --header 'Content-Type: application/json' \
  --header 'X-MSS-API-APPID: <api-key>' \
  --header 'X-MSS-API-USERKEY: <api-key>' \
  --header 'X-MSS-CUSTOM-DATE: <api-key>' \
  --header 'X-MSS-SIGNATURE: <api-key>' \
  --data '
{
  "cost": 759.6,
  "costPercentage": 63.6,
  "costPercentageBasis": "PartTotal",
  "setDefault": false,
  "updateAllInstances": false
}
'

import requests

url = "https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/cost"

payload = {
    "cost": 759.6,
    "costPercentage": 63.6,
    "costPercentageBasis": "PartTotal",
    "setDefault": False,
    "updateAllInstances": False
}
headers = {
    "Accept": "<accept>",
    "X-MSS-API-APPID": "<api-key>",
    "X-MSS-API-USERKEY": "<api-key>",
    "X-MSS-CUSTOM-DATE": "<api-key>",
    "X-MSS-SIGNATURE": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Accept: '<accept>',
    'X-MSS-API-APPID': '<api-key>',
    'X-MSS-API-USERKEY': '<api-key>',
    'X-MSS-CUSTOM-DATE': '<api-key>',
    'X-MSS-SIGNATURE': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cost: 759.6,
    costPercentage: 63.6,
    costPercentageBasis: 'PartTotal',
    setDefault: false,
    updateAllInstances: false
  })
};

fetch('https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/cost', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "id": 81376,
    "parentId": 42344,
    "itemType": "Part",
    "referencedItemId": 63140,
    "createdDate": "2030-08-21T00:22:19Z",
    "lastModifiedDate": "2031-02-06T00:22:19Z",
    "brand": "Sonos",
    "model": "Amp",
    "name": "Installation Labor",
    "shortDescription": "Sonos Amp",
    "clientNote": "Mounted in the rack behind the display.",
    "imageUrl": "https://images.portal.io/catalog/sonos-amp.jpg",
    "msrp": 901.23,
    "sellPrice": 583.78,
    "cost": 759.6,
    "costUpdateDate": "2030-11-10T00:22:19Z",
    "supplier": "Sonos Inc.",
    "quantity": 9.6,
    "total": {
      "amount": 982.49,
      "currency": {
        "code": "USD",
        "symbol": "$"
      },
      "isCombinedPrice": false
    },
    "isTaxExempt": false,
    "isRecurringService": false,
    "linkedOrders": [
      {
        "orderId": 21802,
        "orderNumber": 182,
        "orderNumberSuffix": "A",
        "supplier": "Sonos Inc.",
        "supplierRef": "SN-10420",
        "orderName": "Living Room Sonos Amp",
        "orderStatus": "Submitted"
      }
    ]
  }
]

{
  "responseStatus": {
    "errorCode": "BadRequest",
    "message": "Neither an absolute cost nor a percentage was supplied, both were supplied, or a percentage was supplied without its basis."
  }
}

{
  "responseStatus": {
    "errorCode": "Unauthorized",
    "message": "Not Authorized. Ensure a valid session cookie or HMAC authentication headers are provided."
  }
}

{
  "responseStatus": {
    "errorCode": "PaymentRequired",
    "message": "The dealer's subscription is inactive or expired. An active subscription is required to use this endpoint."
  }
}

{
  "responseStatus": {
    "errorCode": "Forbidden",
    "message": "You do not have permission for this action."
  }
}

{
  "responseStatus": {
    "errorCode": "NotFound",
    "message": "Proposal or proposal item not found."
  }
}

{
  "responseStatus": {
    "errorCode": "Conflict",
    "message": "Proposal is in a state that does not allow editing."
  }
}

Sets the per-unit supplier cost of a proposal item, as either an absolute Cost or a CostPercentage plus CostPercentageBasis. Exactly one of the two forms is required: supplying both, neither, or a percentage without its basis returns 400. As with sell price, the two forms replace each other. Percentages are whole numbers — 15 means 15%, rounded to 2 decimals. The bases match update sell price, plus CostOfSellPrice, which is valid for cost only and makes the cost a percentage of the item’s own sell price. Every basis is resolved when the proposal is read, not when you write it, so a percentage cost is never a fixed number: ProposalTotal, PartTotal, and LaborTotal move with the whole proposal, AreaTotal, PartsInAreaTotal, and LaborInAreaTotal move with the item’s own area option, and CostOfSellPrice moves with the item’s sell price. Re-read the proposal after a batch of writes rather than assuming the cost you sent is the cost stored.

A percentage cost is ignored while the item is marked as a recurring service.

Writing a cost updates the item against its current supplier and refreshes costUpdateDate. It does not change which supplier the item uses — set item supplier does that. cost can come back null even on a successful write, if you do not have permission to see costs — the write still took effect.

A cost written here marks the item as carrying a hand-entered amount, which takes it out of every later refresh item costs run on the proposal. That keeps a price you set on purpose from being reset by a catalog refresh, and there is no flag to opt back in.

SetDefault also saves the cost in the catalog against the supplier the item uses, and updates the company’s draft proposals and draft orders that carry the same part without a cost of their own. For a Part only an absolute cost is saved; a percentage-based update saves nothing and clears any cost saved there before. Labor, CustomItem, and Fee items keep the cost, percentage, and basis on their library item. UpdateAllInstances applies the change to the proposal’s other items from the same source item that share both its item type and its assigned supplier.

Authorizations

X-MSS-API-APPID

string

header

required

Portal application identifier used as part of HMAC-authenticated API requests.

X-MSS-API-USERKEY

string

header

required

Portal user API key used together with the HMAC signature headers.

X-MSS-CUSTOM-DATE

string

header

required

Timestamp header included in the signed request to prevent replay attacks.

X-MSS-SIGNATURE

string

header

required

HMAC-SHA256 signature for the request, calculated over the canonical string defined in the authentication docs.

Headers

enum<string>

required

Accept Header

Available options:

application/json

Path Parameters

ProposalId

integer<int32>

required

Unique ID of the proposal (not the proposal number).

ProposalItemId

integer<int32>

required

Id of the proposal item to update. Must belong to the proposal.

Body

application/json

Proposals Service

cost

number<double>

Absolute per-unit supplier cost, mutually exclusive with costPercentage. Supplying it clears any stored percentage and basis.

costPercentage

number<double>

Cost as a whole percent of the chosen basis (15 means 15%), with the resulting cost rounded to 2 decimals. Requires costPercentageBasis, is mutually exclusive with cost, and clears any stored absolute cost. Ignored while the item is a recurring service.

costPercentageBasis

enum<string>

Available options:

ProposalTotal,

PartTotal,

LaborTotal,

AreaTotal,

PartsInAreaTotal,

LaborInAreaTotal,

CostOfSellPrice

setDefault

boolean

When true, also save this cost in the catalog so later proposals start with it. For a Part, only an absolute cost is saved, against the supplier the item uses: a percentage-based update saves no cost and clears any cost saved there before. The company's draft proposals and draft orders that carry that part without a cost of their own are updated too. For a Labor, CustomItem, or Fee item, the cost, percentage, and basis are saved on the library item. Defaults to false.

updateAllInstances

boolean

When true, apply the change to every other instance of the same catalog item in this proposal that shares its item type and assigned supplier, across all area options. Defaults to false.

Response

Success

integer<int32>

required

Unique numeric identifier of the proposal item

referencedItemId

integer<int32>

required

Identifier of the catalog, labor, custom, or fee item this proposal item was created from

createdDate

string<date-time>

required

UTC timestamp when the proposal item was created

quantity

number<double>

required

Quantity of the proposal item

parentId

integer<int32>

Identifier of the parent item when this item is nested under another item

itemType

enum<string>

Available options:

Part,

Labor,

CustomItem,

Fee

lastModifiedDate

string<date-time>

UTC timestamp when the proposal item was last modified

brand

string

Brand name of the item

model

string

Model value of the item

name

string

Name of a Labor item

shortDescription

string

Short description shown for the proposal item

clientNote

string

Client-facing note for the proposal item

imageUrl

string

Image URL of the item

msrp

number<double>

MSRP amount of the item

sellPrice

number<double>

Sell price for the proposal item

cost

number<double>

Supplier cost for the proposal item

costUpdateDate

string<date-time>

UTC timestamp when the supplier cost was last updated

supplier

string

Display name of the supplier assigned to the item.

total

PublicItemTotalModel · object

Total amount for a proposal item

Show child attributes

isTaxExempt

boolean

Whether the proposal item is tax exempt

isRecurringService

boolean

Whether the proposal item is a recurring service

linkedOrders

PublicLinkedOrderModel · object[]

Linked orders created from this proposal item

Show child attributes

⌘I

Authentication

Proposals

Proposal Items

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Update Proposal Item Supplier Cost

Authorizations

Headers

Path Parameters

Body

Response