Use of External Options

In this article:

• What are External Options?
• How to set up external values in CPQ
• Use Case
• Limitations

What are External Options?

The External Values option enables CPQ to receive and convert data from external sources, such as Vendor APIs.

CPQ offers 3 external use options:

1. Use External Values - Useful to retrieve subscription id's, statuses - it is not possible to have such value defined in pricing plan in advance.

2. Use external Values with prices - Allows to set multiple values which will be returned from external source, supports price setup for each unique value. Missing values will result failure for a specific configuration.

3. Run External Validation - allows to validate configuration. As an example: customer has 5 licenses of a particular subscriptions and wants to change license count to 4, this data is sent to vendor API to validate whether it is allowed to have 4 in form data.

Whenever there is an update to the form in buy page, any control is changed or clicked All the fields with external options enabled in CPQ will create API calls to api/integration/externalOptions endpoint and then this information will be sent to AI to process.

How to set up external values in CPQ:

1. Create or edit existing Pricing Plan:

2. Add dropdown or multi dropdown to the form:

3. Check "Use external values with prices" on the dropdown element and fill in the values which will be used by sequences later:

Use Case 

As an example, we have Vendor Offer with offer levels which are received from Vendor API. In this scenario customers has specific levels which define the discount applied to the offers. Receiving the correct level will adjust the price.

Request is being sent to the following Vendor endpoint:

examplevendor/¦AzureTenant.ExternalId§/orders

The Level is received for the corresponding setup of the customer on the Vendor side using Vendor Customer ID

With following parameters:

{
  "currencyCode": "EUR",
  "orderType": "PREVIEW",
  "lineItems": [
    {
      "extLineItemNumber": 1,
      "offerId": "¦Offer.VendorExternalId§",
      "quantity": "¦customerInput.LicenseQuantityKey§"
    }
  ]
}

And returns the Level which then is displayed on UI:

{
    "creationDate": "2024-01-23T11:41:43Z",
    "currencyCode": "EUR",
    "customerId": "P1005076435",
    "externalReferenceId": "",
    "lineItems": [
        {
            "extLineItemNumber": 1,
            "offerId": "65327721CA01A12",
            "quantity": 1,
            "status": "",
            "subscriptionId": ""
        }
    ],
    "orderId": "",
    "orderType": "PREVIEW",
    "referenceOrderId": "",
    "status": ""
}

The sequence is executed based on these conditions:

{
  "uniqueKey": "priceLevelKey",
  "¦AzureTenant.ExternalId§": "#notblank",
  "¦customerInput.action§": "placeOrder"
}

"uniqueKey" is the indication which field is using the external options

Payload received by CPQ:

[
    {
        "title": {
            "en-US": "Level 1   (65327721CA01A12)"
        },
        "value": "65327721CA01A12"
    }
]

Response Sequence for above payload:

[
    {
        "title": {
            "en-US": "¦DynamicParams.Level§　　　Part Number: ¦DynamicParams.offerLevelId§"
        },
        "value": "¦DynamicParams.offerLevelId§"
    }
]

It is defined by Sequences with Operation "GetExternalData"

Payload sent to AI:

{
  "customerId": "",
  "customerInput": {},
  "action": "",
  "universalTenantDomainKey": {
    "DomainName": "",
    "InternalId": ""
  },
  "ExternalId": "",
  "effectiveDate": "",
  "offerId": "",
  "operation": "",
  "resellerId": "",
  "uniqueKey": "",
  "userId": "",
  "vendorId": ""
}

Example of the response sequence which returns data to CPQ:

{
	"Id" : "02379CCC-09BC-42CB-BA9E-5F80EBB7108A",
	"Link" : "",
	"Sequence" : 115,
	"Params" : "",
	"Hints" : "{\"EnforceUtf8\":true,'STOP':'STOP'}",
	"Method" : "RESPONSE",
	"Response" : "[{'value': '¦DynamicParams.offerLevelId§','title': {'en-US': '¦DynamicParams.Level§   (¦DynamicParams.offerLevelId§)'}}]",
	"OfferId" : "00000000-0000-0000-0000-000000000000",
	"Header" : "",
	"ExecutionCondition" : "{'uniqueKey':'priceLevelKey','¦customerInput.action§':'placeOrder','¦DynamicParams.Level§':'#notblank'}",
	"ExternalMapping" : "",
	"ExternalSystemId" : "00000000-0000-0000-0000-000000000000",
	"Comments" : "LEVEL DISCOUNT - Return successful values",
	"RethinkMapping" : "",
	"Operation" : "GetExternalData",
	"VendorTenantId" : "00000000-0000-0000-0000-000000000000",
	"PlatformId" : "00000000-0000-0000-0000-000000000000",
	"VendorId" : "02F64CF6-E340-4086-A244-315D0E61534F",
	"Source" : "SequenceUploader",
	"CreatedBy" : null,
	"CreatedDate" : null
}

If Multi dropdown is being used:

With following values:

Process is similar, except the output contains array with values, for example:

{
  "OfferId": "",
  "FormData": {
    "dropdownKey": ["value1", "value2", "value3", "value4"],
    "numberKey": 1
  },
  "OrderDate": "2024-01-23T00:00:00Z",
  "ParentOfferId": null
}

And response sent to CPQ is following:

[
    {
        "value": "value1",
        "title": {
            "en-US": "Create an Order"
        }
    },
    {
        "value": "value2",
        "title": {
            "en-US": "some option1"
        }
    },
    {
        "value": "value3",
        "title": {
            "en-US": "some option2"
        }
    },
    {
        "value": "value4",
        "title": {
            "en-US": "some option3"
        }
    }
]

Limitations

1. If "Use external options with prices" is used on subscription edit page the dropdown will contain all options and won't be updated until user clicks inside any field that will trigger the external data update call. In subscription edit page when opening:

After clicking any field:

2. Dynamic control will not work if "Use external values" option is selected:

3. If field is not read only and the value is empty or null CPQ will load the new value from AI and cause no issues. If field is read only and empty or null during checkout there will be the following error:

Summary

External Options in CPQ enable Product Management to receive and convert data from external sources such as Vendor APIs. Three external use options are available: "Use External Values" for retrieving dynamic data like Subscription IDs and statuses, "Use external Values with prices" for setting multiple values with Price configurations, and "Run External Validation" for validating configurations against Vendor APIs. External Options are configured by adding Dropdown or Multi Dropdown controls to Offer forms and enabling external values settings. When Customers interact with forms, the Platform creates API calls to retrieve external data and process it through integration sequences. External Options have limitations: dropdown controls on Subscription edit pages don't update until Customers trigger field interactions, dynamic controls don't work with "Use external values" enabled, and read-only fields with empty values cause errors during checkout. This feature enables sophisticated Offer configurations that integrate real-time Vendor data for provisioning, pricing adjustments, and validation workflows.