> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace a Proposal Item

> POST /public/proposals/{ProposalId}/items/{ProposalItemId}/replace — Swaps a proposal item for a different catalog item.

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          |

<Warning>
  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.
</Warning>

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

<Snippet file="hmac-signing.mdx" />


## OpenAPI

````yaml POST /public/proposals/{ProposalId}/items/{ProposalItemId}/replace
openapi: 3.1.1
info:
  title: Portal.io Public API
  version: '1.0'
servers:
  - url: https://sandbox.api.portal.io/
security:
  - mssApiAppId: []
    mssApiUserKey: []
    mssCustomDate: []
    mssSignature: []
paths:
  /public/proposals/{ProposalId}/items/{ProposalItemId}/replace:
    post:
      tags:
        - Proposals/Item
      summary: Replace Proposal Item
      description: >-
        Replaces a proposal item with a different catalog item. The new item
        keeps the original's quantity, position, area option, parent and
        combined-pricing setting. Its supplier, prices, MSRP, tax-exempt and
        recurring-service settings, image, brand, model and description come
        from the catalog item you name. The original item is removed and its id
        stops working. The response lists the new item - or items, when
        replaceAll is used - along with any attachment items added with them.
      operationId: postPublicProposalsByProposalIdItemsByProposalItemIdReplace
      parameters:
        - name: ProposalId
          in: path
          required: true
          explode: true
          schema:
            type: integer
            description: Unique ID of the proposal (not the proposal number).
            format: int32
            x-default: 11538
        - name: ProposalItemId
          in: path
          required: true
          explode: true
          schema:
            type: integer
            description: Id of the proposal item to replace.
            format: int32
            x-default: 92853
        - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicProposalItemReplaceRequest'
            example:
              newCatalogItemId: 70270
              itemType: Part
              replaceAll: false
              includeAttachments: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: ListOfPublicAreaItemModel
                type: array
                items:
                  $ref: '#/components/schemas/PublicAreaItemModel'
              example:
                - 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
        '400':
          description: >-
            itemType is missing or not a known item type, or newCatalogItemId is
            missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                responseStatus:
                  errorCode: BadRequest
                  message: >-
                    itemType is missing or not a known item type, or
                    newCatalogItemId is missing.
        '401':
          description: >-
            Not Authorized. Ensure a valid session cookie or HMAC authentication
            headers are provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                responseStatus:
                  errorCode: Unauthorized
                  message: >-
                    Not Authorized. Ensure a valid session cookie or HMAC
                    authentication headers are provided.
        '402':
          description: >-
            The dealer's subscription is inactive or expired. An active
            subscription is required to use this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                responseStatus:
                  errorCode: PaymentRequired
                  message: >-
                    The dealer's subscription is inactive or expired. An active
                    subscription is required to use this endpoint.
        '403':
          description: You do not have permission for this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                responseStatus:
                  errorCode: Forbidden
                  message: You do not have permission for this action.
        '404':
          description: Proposal or item not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                responseStatus:
                  errorCode: NotFound
                  message: Proposal or item not found.
        '409':
          description: Proposal state prevents editing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                responseStatus:
                  errorCode: Conflict
                  message: Proposal state prevents editing
components:
  parameters:
    Accept:
      name: Accept
      in: header
      description: Accept Header
      required: true
      schema:
        enum:
          - application/json
        type: string
  schemas:
    PublicProposalItemReplaceRequest:
      title: PublicProposalItemReplaceRequest
      required:
        - newCatalogItemId
      type: object
      properties:
        newCatalogItemId:
          type: integer
          description: >-
            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.
          format: int32
        itemType:
          $ref: '#/components/schemas/ItemTypes'
        replaceAll:
          type: boolean
          description: >-
            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:
          type: boolean
          description: >-
            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.
      description: Proposals Service
    PublicAreaItemModel:
      title: PublicAreaItemModel
      required:
        - id
        - referencedItemId
        - createdDate
        - quantity
      type: object
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the proposal item
          format: int32
        parentId:
          type: integer
          description: >-
            Identifier of the parent item when this item is nested under another
            item
          format: int32
        itemType:
          $ref: '#/components/schemas/ItemTypes'
        referencedItemId:
          type: integer
          description: >-
            Identifier of the catalog, labor, custom, or fee item this proposal
            item was created from
          format: int32
        createdDate:
          type: string
          description: UTC timestamp when the proposal item was created
          format: date-time
        lastModifiedDate:
          type: string
          description: UTC timestamp when the proposal item was last modified
          format: date-time
        brand:
          type: string
          description: Brand name of the item
        model:
          type: string
          description: Model value of the item
        name:
          type: string
          description: Name of a Labor item
        shortDescription:
          type: string
          description: Short description shown for the proposal item
        clientNote:
          type: string
          description: Client-facing note for the proposal item
        imageUrl:
          type: string
          description: Image URL of the item
        msrp:
          type: number
          description: MSRP amount of the item
          format: double
        sellPrice:
          type: number
          description: Sell price for the proposal item
          format: double
        cost:
          type: number
          description: Supplier cost for the proposal item
          format: double
        costUpdateDate:
          type: string
          description: UTC timestamp when the supplier cost was last updated
          format: date-time
        supplier:
          type: string
          description: Display name of the supplier assigned to the item.
        quantity:
          type: number
          description: Quantity of the proposal item
          format: double
        total:
          $ref: '#/components/schemas/PublicItemTotalModel'
        isTaxExempt:
          type: boolean
          description: Whether the proposal item is tax exempt
        isRecurringService:
          type: boolean
          description: Whether the proposal item is a recurring service
        linkedOrders:
          type: array
          items:
            $ref: '#/components/schemas/PublicLinkedOrderModel'
          description: Linked orders created from this proposal item
      description: Proposal area item
    ErrorResponse:
      title: ErrorResponse
      type: object
      properties:
        responseStatus:
          $ref: '#/components/schemas/ResponseStatus'
      description: ErrorResponse
    ItemTypes:
      enum:
        - Part
        - Labor
        - CustomItem
        - Fee
      type: string
    PublicItemTotalModel:
      title: PublicItemTotalModel
      required:
        - amount
      type: object
      properties:
        amount:
          type: number
          description: Per-unit sell price multiplied by quantity, before tax
          format: double
        currency:
          $ref: '#/components/schemas/PublicCurrencyModel'
        isCombinedPrice:
          type: boolean
          description: >-
            Whether the totals of nested items are included in this item's
            amount
      description: Total amount for a proposal item
    PublicLinkedOrderModel:
      title: PublicLinkedOrderModel
      required:
        - orderId
        - orderNumber
        - orderNumberSuffix
        - orderName
      type: object
      properties:
        orderId:
          type: integer
          description: Unique numeric identifier of the order
          format: int32
        orderNumber:
          type: integer
          description: Order number shown to the dealer
          format: int32
        orderNumberSuffix:
          type: string
          description: Order number suffix used for supplier-specific numbering
        supplier:
          type: string
          description: Supplier display name
        supplierRef:
          type: string
          description: Supplier reference or supplier order number
        orderName:
          type: string
          description: Display name of the order
        orderStatus:
          $ref: '#/components/schemas/OrderStatuses'
      description: Order summary linked to a proposal item
    ResponseStatus:
      title: ResponseStatus
      type: object
      properties:
        errorCode:
          type:
            - 'null'
            - string
        message:
          type:
            - 'null'
            - string
        stackTrace:
          type:
            - 'null'
            - string
        errors:
          type:
            - 'null'
            - array
          items:
            $ref: '#/components/schemas/ResponseError'
        meta:
          title: DictionaryOfStringAndString
          type:
            - 'null'
            - object
          additionalProperties:
            type:
              - 'null'
              - string
      description: ResponseStatus
    PublicCurrencyModel:
      title: PublicCurrencyModel
      required:
        - code
        - symbol
      type: object
      properties:
        code:
          type: string
          description: ISO 4217 code that identifies the currency used for the amount.
        symbol:
          type: string
          description: Symbol displayed alongside monetary values in this currency.
      description: Currency code and symbol used to display money values.
    OrderStatuses:
      enum:
        - Draft
        - Submitted
        - ViewedBySupplier
        - Accepted
        - Received
        - EmailFailed
        - Undefined
      type: string
    ResponseError:
      title: ResponseError
      type: object
      properties:
        errorCode:
          type:
            - 'null'
            - string
        fieldName:
          type:
            - 'null'
            - string
        message:
          type:
            - 'null'
            - string
        meta:
          title: DictionaryOfStringAndString
          type:
            - 'null'
            - object
          additionalProperties:
            type:
              - 'null'
              - string
      description: ResponseError
  securitySchemes:
    mssApiAppId:
      type: apiKey
      description: >-
        Portal application identifier used as part of HMAC-authenticated API
        requests.
      name: X-MSS-API-APPID
      in: header
    mssApiUserKey:
      type: apiKey
      description: Portal user API key used together with the HMAC signature headers.
      name: X-MSS-API-USERKEY
      in: header
    mssCustomDate:
      type: apiKey
      description: >-
        Timestamp header included in the signed request to prevent replay
        attacks.
      name: X-MSS-CUSTOM-DATE
      in: header
    mssSignature:
      type: apiKey
      description: >-
        HMAC-SHA256 signature for the request, calculated over the canonical
        string defined in the authentication docs.
      name: X-MSS-SIGNATURE
      in: header

````