Replace a Proposal Item

Replace Proposal Item

curl --request POST \
  --url https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/replace \
  --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 '
{
  "newCatalogItemId": 70270,
  "itemType": "Part",
  "replaceAll": false,
  "includeAttachments": false
}
'

import requests

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

payload = {
    "newCatalogItemId": 70270,
    "itemType": "Part",
    "replaceAll": False,
    "includeAttachments": 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({
    newCatalogItemId: 70270,
    itemType: 'Part',
    replaceAll: false,
    includeAttachments: false
  })
};

fetch('https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/replace', 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": "itemType is missing or not a known item type, or newCatalogItemId is missing."
  }
}

{
  "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 item not found."
  }
}

{
  "responseStatus": {
    "errorCode": "Conflict",
    "message": "Proposal state prevents editing"
  }
}

POST

public

proposals

{ProposalId}

items

{ProposalItemId}

replace

Replace Proposal Item

curl --request POST \
  --url https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/replace \
  --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 '
{
  "newCatalogItemId": 70270,
  "itemType": "Part",
  "replaceAll": false,
  "includeAttachments": false
}
'

import requests

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

payload = {
    "newCatalogItemId": 70270,
    "itemType": "Part",
    "replaceAll": False,
    "includeAttachments": 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({
    newCatalogItemId: 70270,
    itemType: 'Part',
    replaceAll: false,
    includeAttachments: false
  })
};

fetch('https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/replace', 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": "itemType is missing or not a known item type, or newCatalogItemId is missing."
  }
}

{
  "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 item not found."
  }
}

{
  "responseStatus": {
    "errorCode": "Conflict",
    "message": "Proposal state prevents editing"
  }
}

Swaps a proposal item for a different source item, named by NewCatalogItemId. ItemType describes the incoming item and does not have to match the type of the one being replaced. What survives the swap and what comes from the new item:

Kept from the original	Taken from the replacement
Quantity, position, area option	Supplier, sell price, cost, MSRP
Parent item, combined-pricing setting	Tax-exempt and recurring-service settings
	Image, brand, model, description

The original item is removed and its id is no longer valid. Read the new id from the response before making any further per-item calls, and drop any id you had cached.

ReplaceAll extends the swap to the proposal’s other items that come from the same source item and share its item type; instances sitting in a declined area option are left alone. Defaults to false. IncludeAttachments also adds the items attached to each replacement, nested under it. It defaults to false here and requires the account’s plan to include product attachments. Attachment items are listed in the response along with the replacements.

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 replace.

Body

application/json

Proposals Service

newCatalogItemId

integer<int32>

required

Identifier of the source item to replace with, matching itemType. Part ids come from GET /public/catalog; ids for Labor, CustomItem, and Fee items are not exposed by the public API yet.

itemType

enum<string>

Available options:

Part,

Labor,

CustomItem,

Fee

replaceAll

boolean

When true, also replace every other instance of the same catalog item in this proposal that shares its item type. Instances sitting in a declined area option are left alone. Defaults to false.

includeAttachments

boolean

When true, also add the items attached to each replacement item, nested under it. Requires the account's plan to include product attachments. 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

Authorizations

Headers

Path Parameters

Body

Response