Add Items to a Proposal

Add Proposal Items

curl --request POST \
  --url https://sandbox.api.portal.io/public/proposals/{ProposalId}/items \
  --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 '
{
  "items": [
    {
      "catalogItemId": 86570,
      "itemType": "Part",
      "proposalAreaOptions": [
        {
          "proposalAreaOptionId": 57002,
          "quantity": 9.6
        }
      ],
      "supplierId": 92492,
      "sellPrice": 583.78,
      "sellPercentage": 52.31,
      "sellPercentageBasis": "PartTotal",
      "cost": 759.6,
      "costPercentage": 63.6,
      "costPercentageBasis": "PartTotal",
      "model": "Amp",
      "name": "Installation Labor",
      "msrp": 901.23,
      "isRecurringService": false,
      "isTaxExempt": false,
      "setDefault": false,
      "parentProposalItemIds": [
        77287,
        10024
      ]
    }
  ],
  "includeAttachments": true
}
'

import requests

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

payload = {
    "items": [
        {
            "catalogItemId": 86570,
            "itemType": "Part",
            "proposalAreaOptions": [
                {
                    "proposalAreaOptionId": 57002,
                    "quantity": 9.6
                }
            ],
            "supplierId": 92492,
            "sellPrice": 583.78,
            "sellPercentage": 52.31,
            "sellPercentageBasis": "PartTotal",
            "cost": 759.6,
            "costPercentage": 63.6,
            "costPercentageBasis": "PartTotal",
            "model": "Amp",
            "name": "Installation Labor",
            "msrp": 901.23,
            "isRecurringService": False,
            "isTaxExempt": False,
            "setDefault": False,
            "parentProposalItemIds": [77287, 10024]
        }
    ],
    "includeAttachments": True
}
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({
    items: [
      {
        catalogItemId: 86570,
        itemType: 'Part',
        proposalAreaOptions: [{proposalAreaOptionId: 57002, quantity: 9.6}],
        supplierId: 92492,
        sellPrice: 583.78,
        sellPercentage: 52.31,
        sellPercentageBasis: 'PartTotal',
        cost: 759.6,
        costPercentage: 63.6,
        costPercentageBasis: 'PartTotal',
        model: 'Amp',
        name: 'Installation Labor',
        msrp: 901.23,
        isRecurringService: false,
        isTaxExempt: false,
        setDefault: false,
        parentProposalItemIds: [77287, 10024]
      }
    ],
    includeAttachments: true
  })
};

fetch('https://sandbox.api.portal.io/public/proposals/{ProposalId}/items', 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": "Invalid item payload, or name/model supplied on an item type that does not accept it."
  }
}

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

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

POST

public

proposals

{ProposalId}

items

Add Proposal Items

curl --request POST \
  --url https://sandbox.api.portal.io/public/proposals/{ProposalId}/items \
  --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 '
{
  "items": [
    {
      "catalogItemId": 86570,
      "itemType": "Part",
      "proposalAreaOptions": [
        {
          "proposalAreaOptionId": 57002,
          "quantity": 9.6
        }
      ],
      "supplierId": 92492,
      "sellPrice": 583.78,
      "sellPercentage": 52.31,
      "sellPercentageBasis": "PartTotal",
      "cost": 759.6,
      "costPercentage": 63.6,
      "costPercentageBasis": "PartTotal",
      "model": "Amp",
      "name": "Installation Labor",
      "msrp": 901.23,
      "isRecurringService": false,
      "isTaxExempt": false,
      "setDefault": false,
      "parentProposalItemIds": [
        77287,
        10024
      ]
    }
  ],
  "includeAttachments": true
}
'

import requests

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

payload = {
    "items": [
        {
            "catalogItemId": 86570,
            "itemType": "Part",
            "proposalAreaOptions": [
                {
                    "proposalAreaOptionId": 57002,
                    "quantity": 9.6
                }
            ],
            "supplierId": 92492,
            "sellPrice": 583.78,
            "sellPercentage": 52.31,
            "sellPercentageBasis": "PartTotal",
            "cost": 759.6,
            "costPercentage": 63.6,
            "costPercentageBasis": "PartTotal",
            "model": "Amp",
            "name": "Installation Labor",
            "msrp": 901.23,
            "isRecurringService": False,
            "isTaxExempt": False,
            "setDefault": False,
            "parentProposalItemIds": [77287, 10024]
        }
    ],
    "includeAttachments": True
}
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({
    items: [
      {
        catalogItemId: 86570,
        itemType: 'Part',
        proposalAreaOptions: [{proposalAreaOptionId: 57002, quantity: 9.6}],
        supplierId: 92492,
        sellPrice: 583.78,
        sellPercentage: 52.31,
        sellPercentageBasis: 'PartTotal',
        cost: 759.6,
        costPercentage: 63.6,
        costPercentageBasis: 'PartTotal',
        model: 'Amp',
        name: 'Installation Labor',
        msrp: 901.23,
        isRecurringService: false,
        isTaxExempt: false,
        setDefault: false,
        parentProposalItemIds: [77287, 10024]
      }
    ],
    includeAttachments: true
  })
};

fetch('https://sandbox.api.portal.io/public/proposals/{ProposalId}/items', 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": "Invalid item payload, or name/model supplied on an item type that does not accept it."
  }
}

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

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

Adds items to a proposal. Each entry in Items names a source item, its type, and the area options to put it in — one item is created per area option the entry targets. Area option ids come from get proposal; see reading proposal items for where to find them. The response is the standard List<PublicAreaItemModel> array of created items.

Item types and their ids

CatalogItemId means a different thing for each ItemType, and each type takes the item’s name in a different field:

`ItemType`	`CatalogItemId` refers to	Send the name in	Read back as
`Part`	A catalog item, searchable with search catalog items	`Model`	`model`
`CustomItem`	A custom item in the account’s library	`Model`	`model`
`Labor`	A labor item in the account’s library	`Name`	`name`
`Fee`	A fee item in the account’s library	`Name`	`model`

Supplying the wrong one for the type — Name on a Part, Model on a Labor item — returns 400. SupplierId applies to Part items only; omit it to use the part’s default supplier.

Only Part ids are discoverable through the public API today. There is no public endpoint that lists the account’s labor, custom, or fee items, so ids for those types have to come from elsewhere until one ships.

Pricing a new item

Omit SellPrice and SellPercentage and the item inherits the catalog item’s default sell price; the same applies to Cost and CostPercentage. Supply one of each pair to override — an absolute amount, or a whole-percent value plus its basis (15 means 15%). Send exactly one member of each pair. Unlike update sell price and update cost, this endpoint does not check the pair for you, so a mistake here fails quietly instead of returning a 400. Send both members and the percentage is used, ignoring the absolute amount. Send a percentage without its basis and there is nothing to calculate it from, so the item is created with no price at all. Per-item SetDefault saves this item’s sell price as the default on the catalog item, so later proposals start with it. It persists nothing else on the item.

This endpoint is not idempotent. A retried call adds another copy of the item rather than reconciling with the first, so confirm with get proposal before repeating a request that may have already landed.

Nesting and attachments

ParentProposalItemIds nests the new item under an existing one. Matching is per area option: in each target option, the new item nests under whichever listed parent lives in that same option, and sits at top level where none does. Nesting is read back as parentId, and children’s prices can be folded into the parent’s displayed total with set combined pricing. IncludeAttachments is separate — it adds the items the catalog item is configured to bring along, nested under the new item. It defaults to true; pass false to skip them. Attachment items are not part of this call’s response and may take a moment to appear, so re-fetch the proposal to read them.

Adding several items at once

items takes any number of entries, and they do not have to be the same type. This call adds a Part and a Labor line to area option 201, with the part nested under the existing item 5000:

{
  "items": [
    {
      "catalogItemId": 88213,
      "itemType": "Part",
      "parentProposalItemIds": [5000],
      "proposalAreaOptions": [{ "proposalAreaOptionId": 201, "quantity": 2 }]
    },
    {
      "catalogItemId": 730,
      "itemType": "Labor",
      "name": "Installation Labor",
      "proposalAreaOptions": [{ "proposalAreaOptionId": 201, "quantity": 5.5 }]
    }
  ]
}

The part nests under 5000 because that item sits in option 201; where none of the listed parents lives in a target option, the new item is added at that option’s top level instead. The labor line names no parent, so it starts at top level. Each entry is created once per area option it lists, so adding further proposalAreaOptions entries places copies across several options in the same call.

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

Body

application/json

Proposals Service

items

PublicProposalItemModel · object[]

required

New items to add to the proposal. At least one item is required.

Show child attributes

includeAttachments

boolean

(Optional) Also add the items attached to each newly created item, nested under it. Defaults to true - pass false to skip. Attachment items are not part of this call's response and may take a moment to appear; re-fetch the proposal to read them.

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

Item types and their ids

Pricing a new item

Nesting and attachments

Adding several items at once

Authorizations

Headers

Path Parameters

Body

Response

​Item types and their ids

​Pricing a new item

​Nesting and attachments

​Adding several items at once

Authorizations

Headers

Path Parameters

Body

Response

Item types and their ids

Pricing a new item

Nesting and attachments

Adding several items at once