Available tools

36 min

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"]
    }
  ]
}