Initiate Swap (POST)

Exchange one product for another of equivalent or different value. The change is tracked as a swap request with linked asset actions and a net-zero order total where applicable. The API creates an amendment quote and order with order actions and quote action subtypes.

When the order is assetized, the source asset gets an asset action with business category as Swap (reduced quantity). The new asset is created with an asset action that identifies it as swapped in, with relationships that link the swapped-from and swapped-to assets. The swaps are auditable and reportable separately from cancellations and new sales. This API also supports use cases such as trading unused licenses for credits or moving spend between products while preserving contract intent.

Resource

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

Resource Example

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

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": "SWAP-001",
8        "outGroup": {
9          "swapAssets": [
10            {
11              "assetId": "02ixx0000004HOAAA2",
12              "quantity": 1
13            }
14          ]
15        },
16        "inGroup": {
17          "graphId": "swapRequest",
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": "2022-09-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 swap.	Optional	66.0
`opportunityId`	String	ID of the opportunity record to swap.	Optional	66.0
`outputRecordType`	String	Record type of the output for the swap.	Required	66.0
`swapGroups`	Swap Group[]	Groups that contain the asset details for the swap.	Required	66.0
`swapStartDate`	String	Amendment start date for the swap action.	Required	66.0

Response Body for POST

Initiate Swap Response

See Also

Salesforce Help: Swap, Upgrade, or Downgrade Assets