Initiate Upgrade (POST)

Move a lower-tier product to a higher-tier product. The change is tracked as an upgrade request with linked asset actions and quote or order line linkage for reporting and auditing. This API creates an amendment quote and order with order actions and quote action subtypes.

The original asset receives an asset action with an Upgrade (or equivalent) business category. This step indicates that the upgrade-from product and the new asset is created with an asset action (upgraded to), with relationships between the two. This step also enables sales reps to process upgrades and makes sure that upgrades are distinguishable in reporting and analytics from cancellations plus new sales.

Resource

1/revenue/transaction-management/assets/actions/upgrade

Resource Example

1https://{yourInstance}.salesforce.com/services/data/v68.0/revenue/transaction-management/assets/actions/upgrade

Available Version

66.0

HTTP Methods

POST

Request Body for POST

JSON Example

1{
2  "swapStartDate": "2025-12-01T00:00:00Z",
3  "outputRecordType": "Quote",
4  "swapGroups": {
5    "groups": [
6      {
7        "referenceId": "UPGRADE-001",
8        "outGroup": {
9          "swapAssets": [
10            {
11              "assetId": "02ixx0000004HOAAA2",
12              "quantity": 1
13            }
14          ]
15        },
16        "inGroup": {
17          "graphId": "upgradeRequest",
18          "records": [
19            {
20              "referenceId": "refQuoteLine0",
21              "record": {
22                "attributes": {
23                  "type": "QuoteLineItem",
24                  "method": "POST"
25                },
26                "Product2Id": "01txx0000006iVlAAI",
27                "PricebookEntryId": "01uxx0000008ym4AAA",
28                "UnitPrice": 1049,
29                "Quantity": "1",
30                "StartDate": "2026-03-22"
31              }
32            }
33          ]
34        }
35      }
36    ]
37  }
38}

Properties

Name	Type	Description	Required or Optional	Available Version
`contractId`	String	ID of the contract record to upgrade.	Optional	66.0
`opportunityId`	String	ID of the opportunity record to upgrade.	Optional	66.0
`outputRecordType`	String	Record type of the output for the upgrade.	Required	66.0
`swapGroups`	Swap Group[]	Groups that contain the asset details for the upgrade.	Required	66.0
`swapStartDate`	String	Amendment start date for the upgrade action.	Required	66.0

Response Body for POST

Initiate Upgrade Response

See Also

Salesforce Help: Swap, Upgrade, or Downgrade Assets