Available tools

You can use the following Optimizely Opal tools with Optimizely Commerce Connect.

Campaign tools

campaign_types_list

Lists all campaign types in the system. This tool requires no parameters.

Response:

{
  "StatusCode": 200,
  "Message": "Found 3 campaign types",
  "Types": [
    {
      "Name": "SalesCampaign",
      "FullName": "EPiServer.Commerce.Marketing.SalesCampaign",
      "AssemblyQualifiedName": "..."
    }
  ]
}

campaign_filter

Search and filter campaigns using one or more of the following criteria.

Property	Type	Required	Description
`IsActive`	boolean	No	Filter by active status
`Markets`	string	No	Filter by target market IDs
`ValidFrom`	string	No	Campaign start date (ISO 8601)
`ValidUntil`	string	No	Campaign end date (ISO 8601)

Example request:

{
  "IsActive": true,
  "Markets": ["US", "EU"],
  "ValidFrom": "2024-01-01T00:00:00Z"
}

campaign_detail

Retrieve detailed information about a specific campaign.

Property	Type	Required	Description
`Identifier`	string	Yes	Campaign name or ContentReference ID
`IncludeAdditionalDetails`	boolean	No	Audit info and promotions list

Example request:

{
  "Identifier": "Summer Sale 2024",
  "IncludeAdditionalDetails": true
}

Response:

{
  "StatusCode": 200,
  "Message": "Campaign found",
  "Campaign": {
    "Id": "123",
    "Name": "Summer Sale 2024",
    "Description": "Annual summer promotion",
    "ValidFrom": "2024-06-01T00:00:00Z",
    "ValidUntil": "2024-08-31T23:59:59Z",
    "IsActive": true,
    "TargetMarkets": ["US", "EU"],
    "EditLinkUrl": "/episerver/cms/...",
    "Promotions": [
      { "Id": "456", "Name": "20% Off All Items" }
    ]
  }
}

campaign_create

Create a marketing campaign.

Property	Type	Required	Description
`Name`	string	Yes	Campaign name
`Description`	string	No	Campaign description
`ValidFrom`	string	Yes	Start date (ISO 8601)
`ValidUntil`	string	Yes	End date (must be after ValidFrom)

Example request:

{
  "Name": "Black Friday 2024",
  "Description": "Annual Black Friday sale event",
  "ValidFrom": "2024-11-29T00:00:00Z",
  "ValidUntil": "2024-12-02T23:59:59Z"
}

📘
Note
This tool returns a confirmation dialog. The campaign is created after your confirmation.

campaign_update

Update an existing campaign.

Property	Type	Required	Description
`Id`	string	Yes	Campaign ContentReference ID
`Name`	string	No	New campaign name
`Description`	string	No	New campaign description

Example request:

{
  "Id": "123",
  "Name": "Black Friday 2024 - Extended",
  "Description": "Extended Black Friday sale"
}

Promotion tools

promotion_types_list

Lists all promotion types as selectable suggestions. This tool requires no input parameters.

Response:

{
  "Text": "Please select a promotion type:",
  "Suggestions": [
    {
      "Title": "BuyQuantityGetFreeItems",
      "Value": "EPiServer.Commerce.Marketing.Promotions.BuyQuantityGetFreeItems"
    },
    {
      "Title": "BuyQuantityGetItemDiscount",
      "Value": "EPiServer.Commerce.Marketing.Promotions.BuyQuantityGetItemDiscount"
    },
    {
      "Title": "SpendAmountGetOrderDiscount",
      "Value": "EPiServer.Commerce.Marketing.Promotions.SpendAmountGetOrderDiscount"
    }
  ]
}

promotion_filter

Search and filter promotions using one or more of the following criteria.

Property	Type	Required	Description
`Name`	string	No	Partial name match
`IsActive`	boolean	No	Active status filter
`ContentType`	string	No	Content type (defaults to "PromotionData")
`Markets`	string	No	Target market IDs
`ValidFrom`	string	No	Start date filter (ISO 8601)
`ValidUntil`	string	No	End date filter (ISO 8601)

Example request:

{
  "Name": "discount",
  "IsActive": true,
  "Markets": ["US"]
}

promotion_detail

Returns details for a specific promotion.

Property	Type	Required	Description
`Identifier`	string	Yes	Promotion name or ContentReference ID
`IncludeAdditionalDetails`	boolean	No	All properties and audit info

Example request:

{
  "Identifier": "20% Off Electronics",
  "IncludeAdditionalDetails": true
}

Response:

{
  "StatusCode": 200,
  "Message": "Promotion found",
  "Promotion": {
    "Id": "456",
    "Name": "20% Off Electronics",
    "Description": "20% discount on all electronics",
    "IsActive": true,
    "PromotionType": "BuyQuantityGetItemDiscount",
    "FullTypeName": "EPiServer.Commerce.Marketing.Promotions.BuyQuantityGetItemDiscount",
    "CampaignId": "123",
    "Priority": 10,
    "CouponCode": "ELEC20",
    "DiscountType": "Percentage",
    "ValidFrom": "2024-06-01T00:00:00Z",
    "ValidUntil": "2024-08-31T23:59:59Z",
    "EditLinkUrl": "/episerver/cms/...",
    "Properties": [
      {
        "Name": "Condition_RequiredQuantity",
        "Value": 1,
        "PropertyType": "Int32"
      },
      {
        "Name": "Discount_Percentage",
        "Value": 20.0,
        "PropertyType": "Decimal"
      }
    ]
  }
}

promotion_create

Create a promotion within a campaign.

Property	Type	Required	Description
`Name`	string	Yes	Promotion name
`Campaign`	string	Yes	Campaign ID or name
`PromotionType`	string	Yes	Full type name (from `promotion_types_list`)
`Description`	string	No	Promotion description

Example request:

{
  "Name": "Buy 2 Get 1 Free",
  "Campaign": "Summer Sale 2024",
  "PromotionType": "EPiServer.Commerce.Marketing.Promotions.BuyQuantityGetFreeItems",
  "Description": "Buy any 2 items, get 1 free"
}

📘
Note
This tool returns a confirmation dialog. The promotion is created after your confirmation.

promotion_update

Update basic promotion properties.

Property	Type	Required	Description
`Id`	string	Yes	Promotion ContentReference ID
`Name`	string	No	New promotion name
`Description`	string	No	New description
`IsActive`	boolean	No	Active status
`Priority`	integer	No	Priority (lower number = higher priority)

Example request:

{
  "Id": "456",
  "Name": "Buy 2 Get 1 Free - Extended",
  "IsActive": true,
  "Priority": 5
}

promotion_dynamic_update

Update promotion properties using property paths. Supports nested properties.

Property	Type	Required	Description
`Id`	string	Yes	Promotion ContentReference ID
`Properties`	object	No	Dictionary of property paths to values

Property path format: use underscore notation for nested properties.

Condition_RequiredQuantity – RequiredQuantity property of Condition.
Discount_Percentage – Percentage property of Discount.
Reward_AmountOff – AmountOff property of Reward.

Example request (get editable properties):

{
  "Id": "456"
}

Example request (update properties):

{
  "Id": "456",
  "Properties": {
    "Condition_RequiredQuantity": 3,
    "Discount_Percentage": 25.0,
    "IsActive": true
  }
}

promotion_clone

Clones an existing promotion into the same or a different campaign.

Property	Type	Required	Description
`PromotionId`	string	Yes	Source promotion ContentReference ID
`CampaignId`	string	No	Target campaign ID. Defaults to the source promotion's campaign.

Example request:

{
  "PromotionId": "456",
  "CampaignId": "789"
}

📘
Note
This tool returns a confirmation dialog. The promotion is created after your confirmation.

promotion_properties

Returns all properties for a promotion type, including metadata.

Property	Type	Required	Description
`PromotionType`	string	Yes	Type name or full type name

Example request:

{
  "PromotionType": "BuyQuantityGetItemDiscount"
}

Response:

{
  "StatusCode": 200,
  "Message": "Found 15 properties",
  "PromotionType": "BuyQuantityGetItemDiscount",
  "Properties": [
    {
      "Name": "RequiredQuantity",
      "PropertyPath": "Condition_RequiredQuantity",
      "PropertyType": "Int32",
      "DisplayName": "Required Quantity",
      "Description": "Number of items required to trigger promotion",
      "IsRequired": true,
      "MinValue": 1,
      "DefaultValue": 1
    },
    {
      "Name": "Percentage",
      "PropertyPath": "Discount_Percentage",
      "PropertyType": "Decimal",
      "DisplayName": "Discount Percentage",
      "Description": "Percentage discount to apply",
      "IsRequired": true,
      "MinValue": 0,
      "MaxValue": 100
    }
  ]
}

promotion_list_by_sales

List promotions ordered by sales volume (orders placed).

Property	Type	Required	Description
`MarketId`	string	No	Filter by specific market

Example request:

{
  "MarketId": "US"
}

Response:

{
  "items": [
    {
      "PromotionName": "20% Off Everything",
      "PromotionGuid": "abc123...",
      "OrderPlaced": 1250,
      "DiscountType": "Percentage",
      "CouponCode": "SAVE20"
    }
  ]
}

get_validator_properties

Returns properties that have validation requirements for a specific type.

Property	Type	Required	Description
`PromotionType`	string	Yes	Campaign or promotion type name

Example request:

{
  "PromotionType": "BuyQuantityGetFreeItems"
}

Response:

{
  "StatusCode": 200,
  "Message": "Found 3 properties with validators",
  "Properties": [
    "Condition_RequiredQuantity",
    "Reward_NumberOfFreeItems",
    "Discount_Items"
  ]
}

Catalog tools

catalog_query

Queries catalog content using one or more of the following filters.

Property	Type	Required	Description
`ContentType`	string	No	CatalogContent, NodeContent, ProductContent, or VariationContent
`Name`	string	No	Partial name match
`Code`	string	No	Partial code match
`ParentId`	string	No	Parent content ID
`IsAvailable`	boolean	No	Availability filter
`Limit`	integer	No	Results limit. The default is 50.

Example request:

{
  "ContentType": "ProductContent",
  "Name": "shirt",
  "IsAvailable": true,
  "Limit": 20
}

The response includes the following:

Name, ContentType, ContentLink, ParentLink
Type-specific fields (catalog, node, product, variation)
PricePerMarket data for variations
Created, Changed, Language info

Graph tools

com_graph_schema

Retrieve the full GraphQL schema from the Optimizely Graph service. This tool requires no input parameters.

Response: full GraphQL introspection schema (cached for 4 hours).

Query operators

where – Filter results
match – Text search
eq – Exact match
like – Pattern match (use % wildcards)
gte, lte – Range comparisons
in – List membership
_fulltext – Full-text search across all fields
facets – Aggregated results
total(all:true) – Get total count

com_graph_query_executor

Executes custom GraphQL queries against Commerce Graph.

Property	Type	Required	Description
`GraphQLQuery`	string	Yes	The GraphQL query to execute

Example request:

{
  "GraphQLQuery": "query { ProductContent(where: { IsAvailable: { eq: true } }, limit: 10) { items { Name Code } } }"
}

Market tools

commerce_list_market

Lists all markets with their configuration.

Property	Type	Required	Description
`IsEnabledOnly`	boolean	No	Show only enabled markets
`Currency`	string	No	Filter by currency code (USD, EUR, SEK, etc.)
`Language`	string	No	Filter by language code
`MarketId`	string	No	Filter by specific market ID

Example request:

{
  "IsEnabledOnly": true,
  "Currency": "USD"
}

Response:

{
  "StatusCode": 200,
  "Message": "Found 3 markets",
  "Markets": [
    {
      "MarketId": "US",
      "MarketName": "United States",
      "MarketDescription": "US Market",
      "DefaultCurrency": "USD",
      "DefaultLanguage": "en",
      "IsEnabled": true,
      "Countries": ["US"],
      "Languages": ["en", "es"]
    }
  ]
}