# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for VirtoCommerce. Marketing API
  version: 1.0.0
extends: openapi/virto-commerce-marketing-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 35
- target: $.paths['/api/marketing/contentplaces/listentries/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Browse content place folders and entries
      effect: read
      questions:
      - Can I browse content placeholders together with the folders they sit in?
      - What is inside a given folder of dynamic content places?
      instructions:
      - text: List the folders and content places inside folder {folderId}.
        slots:
          folderId: requestBody.folderId
      - text: Browse the content place tree for entries matching {keyword}.
        slots:
          keyword: requestBody.keyword
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentplaces/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search dynamic content places
      effect: read
      questions:
      - How do I find the placeholders on my storefront where dynamic content can show?
      - Can I search content places by keyword without the folders mixed in?
      instructions:
      - text: Search content places for {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: Find only the content places, not folders, in folder {folderId}.
        slots:
          folderId: requestBody.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentitems/listentries/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Browse content item folders and entries
      effect: read
      questions:
      - Can I browse dynamic content items along with the folders that organize them?
      - What content items and subfolders live in a given content folder?
      instructions:
      - text: List the folders and content items inside folder {folderId}.
        slots:
          folderId: requestBody.folderId
      - text: Browse the content item tree for entries matching {keyword}.
        slots:
          keyword: requestBody.keyword
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentitems/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search dynamic content items
      effect: read
      questions:
      - How do I find banners or other dynamic content items by keyword?
      - Can I search only content items, leaving folders out of the results?
      instructions:
      - text: Search dynamic content items for {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: Find only the content items, not folders, in folder {folderId}.
        slots:
          folderId: requestBody.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentpublications/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search content publications
      effect: read
      questions:
      - Which content publications are currently active for my store?
      - Can I find the publications targeting a specific placeholder name?
      instructions:
      - text: List active content publications for store {store}.
        slots:
          store: requestBody.store
      - text: Find publications that target the content place named {placeName}.
        slots:
          placeName: requestBody.placeName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentitems/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Resolve which content to show in a placeholder
      effect: read
      questions:
      - What content should display in a storefront placeholder for this shopper right now?
      - Can dynamic content be targeted by the visitor's country or city?
      - Can I evaluate placeholder content for a specific product page?
      instructions:
      - text: Get the dynamic content to show in place {placeName} for store {storeId}.
        slots:
          placeName: requestBody.placeName
          storeId: requestBody.storeId
      - text: Evaluate content for place {placeName} on product {productId}.
        slots:
          placeName: requestBody.placeName
          productId: requestBody.productId
      - text: Resolve placeholder {placeName} content for a visitor in {geoCountry}.
        slots:
          placeName: requestBody.placeName
          geoCountry: requestBody.geoCountry
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentitems/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dynamic content item
      effect: read
      questions:
      - What does a single dynamic content item, like a banner, contain?
      - Where do I read one content item by its ID?
      instructions:
      - text: Get dynamic content item {id}.
        slots:
          id: path.id
      - text: Show the banner content item {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentitems'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a dynamic content item
      effect: write
      questions:
      - How do I change the image or name of an existing content item?
      - Can I move an existing content item into another folder?
      instructions:
      - text: Update content item {name} with image {imageUrl}.
        slots:
          name: requestBody.name
          imageUrl: requestBody.imageUrl
      - text: Move existing content item {name} to folder {folderId}.
        slots:
          name: requestBody.name
          folderId: requestBody.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentitems'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a dynamic content item
      effect: write
      questions:
      - How do I add a new banner or content block for the storefront?
      - Which content type do I pick when creating a new content item?
      instructions:
      - text: Create a content item {name} of type {contentType}.
        slots:
          name: requestBody.name
          contentType: requestBody.contentType
      - text: Add a new content item {name} in folder {folderId}.
        slots:
          name: requestBody.name
          folderId: requestBody.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentitems'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete dynamic content items
      effect: destructive
      questions:
      - How do I remove banners or content items I no longer use?
      - Can I delete several content items at once?
      instructions:
      - text: Delete content items {ids}.
        slots:
          ids: query.ids
      - text: Remove the dynamic content items with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentplaces/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dynamic content place
      effect: read
      questions:
      - What is defined for one storefront placeholder?
      - Where do I read a single content place by ID?
      instructions:
      - text: Get content place {id}.
        slots:
          id: path.id
      - text: Show the placeholder definition {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentplaces'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a dynamic content place
      effect: write
      questions:
      - How do I rename an existing storefront placeholder?
      - Can I change the description of a content place I already set up?
      instructions:
      - text: Rename content place {id} to {name}.
        slots:
          id: requestBody.id
          name: requestBody.name
      - text: Update the description of content place {id} to {description}.
        slots:
          id: requestBody.id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentplaces'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a dynamic content place
      effect: write
      questions:
      - How do I define a new placeholder slot where content can appear?
      - Can I put a new content place inside a folder?
      instructions:
      - text: Create a content place named {name}.
        slots:
          name: requestBody.name
      - text: Add a new content place {name} in folder {folderId}.
        slots:
          name: requestBody.name
          folderId: requestBody.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentplaces'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete dynamic content places
      effect: destructive
      questions:
      - How do I remove placeholders that are no longer on the storefront?
      - Can I delete several content places together?
      instructions:
      - text: Delete content places {ids}.
        slots:
          ids: query.ids
      - text: Remove the placeholder definitions {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentpublications/new'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank content publication template
      effect: read
      questions:
      - Is there a pre-populated template to start a new content publication from?
      - What does an empty content publication with its default condition tree look like?
      instructions:
      - text: Get a new blank content publication template.
      - text: Give me the default skeleton for a content publication.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentpublications/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a content publication
      effect: read
      questions:
      - What items, places and dates are set on a given content publication?
      - Where do I read one publication by ID?
      instructions:
      - text: Get content publication {id}.
        slots:
          id: path.id
      - text: Show the schedule and targeting of publication {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentpublications'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a content publication
      effect: write
      questions:
      - How do I change when an existing publication starts or ends?
      - Can I deactivate a content publication without deleting it?
      instructions:
      - text: Change publication {name} to run from {startDate} to {endDate}.
        slots:
          name: requestBody.name
          startDate: requestBody.startDate
          endDate: requestBody.endDate
      - text: Set existing publication {name} active flag to {isActive}.
        slots:
          name: requestBody.name
          isActive: requestBody.isActive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentpublications'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a content publication
      effect: write
      questions:
      - How do I schedule content items to appear in placeholders for a store?
      - Can a new publication be limited to a date range?
      instructions:
      - text: Create a publication {name} for store {storeId}.
        slots:
          name: requestBody.name
          storeId: requestBody.storeId
      - text: Publish content items {contentItems} to places {contentPlaces} starting {startDate}.
        slots:
          contentItems: requestBody.contentItems
          contentPlaces: requestBody.contentPlaces
          startDate: requestBody.startDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentpublications'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete content publications
      effect: destructive
      questions:
      - How do I remove content publications I no longer need?
      - Can I delete several publications in one go?
      instructions:
      - text: Delete content publications {ids}.
        slots:
          ids: query.ids
      - text: Remove the publications with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentfolders/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dynamic content folder
      effect: read
      questions:
      - What does a content folder record hold?
      - Where do I read a single content folder by ID?
      instructions:
      - text: Get content folder {id}.
        slots:
          id: path.id
      - text: Show the dynamic content folder {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentfolders'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a dynamic content folder
      effect: write
      questions:
      - How do I rename an existing content folder?
      - Can I move a content folder under a different parent?
      instructions:
      - text: Rename content folder {id} to {name}.
        slots:
          id: requestBody.id
          name: requestBody.name
      - text: Move existing content folder {id} under folder {parentFolderId}.
        slots:
          id: requestBody.id
          parentFolderId: requestBody.parentFolderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentfolders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a dynamic content folder
      effect: write
      questions:
      - How do I create a folder to organize content items and places?
      - Can I nest a new content folder inside another?
      instructions:
      - text: Create a content folder named {name}.
        slots:
          name: requestBody.name
      - text: Add a new content folder {name} inside {parentFolderId}.
        slots:
          name: requestBody.name
          parentFolderId: requestBody.parentFolderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/contentfolders'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete dynamic content folders
      effect: destructive
      questions:
      - How do I remove content folders I no longer use?
      - Can I delete several content folders at once?
      instructions:
      - text: Delete content folders {ids}.
        slots:
          ids: query.ids
      - text: Remove the dynamic content folders {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search promotions
      effect: read
      questions:
      - Which promotions are active in my store right now?
      - Can I list only the public promotions or those in a given status?
      instructions:
      - text: Search promotions for {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: List active promotions in store {store}.
        slots:
          store: requestBody.store
      - text: Find promotions with status {status}.
        slots:
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Calculate which promotions apply to a cart
      effect: read
      questions:
      - Which discounts would a shopper get for this cart total?
      - Can I check whether first-time-buyer promotions apply to a customer?
      - What rewards does the promotion engine return for a given store and currency?
      instructions:
      - text: Evaluate promotions for customer {customerId} in store {storeId}.
        slots:
          customerId: requestBody.customerId
          storeId: requestBody.storeId
      - text: Work out the promotion rewards for a cart total of {cartTotal} {currency}.
        slots:
          cartTotal: requestBody.cartTotal
          currency: requestBody.currency
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a promotion
      effect: read
      questions:
      - What conditions and rewards are set on one promotion?
      - Where do I read a single promotion by ID?
      instructions:
      - text: Get promotion {id}.
        slots:
          id: path.id
      - text: Show the rules of promotion {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/new'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank promotion template
      effect: read
      questions:
      - Is there a starter promotion with the expression tree already filled in?
      - What does an empty dynamic promotion look like before I configure it?
      instructions:
      - text: Get a new blank promotion template.
      - text: Give me the default skeleton for a dynamic promotion.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a promotion
      effect: write
      questions:
      - How do I change the usage limit on an existing promotion?
      - Can I switch an existing promotion off without deleting it?
      instructions:
      - text: Change existing promotion {name} to allow at most {maxUsageCount} uses.
        slots:
          name: requestBody.name
          maxUsageCount: requestBody.maxUsageCount
      - text: Set existing promotion {name} active flag to {isActive}.
        slots:
          name: requestBody.name
          isActive: requestBody.isActive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a promotion
      effect: write
      questions:
      - How do I set up a new discount campaign for my stores?
      - Can a new promotion be exclusive so it doesn't stack with others?
      - Can I limit how many times each customer uses a new promotion?
      instructions:
      - text: Create a promotion {name} for stores {storeIds}.
        slots:
          name: requestBody.name
          storeIds: requestBody.storeIds
      - text: Create an exclusive promotion {name} starting {startDate}.
        slots:
          name: requestBody.name
          startDate: requestBody.startDate
      - text: Add promotion {name} limited to {maxPersonalUsageCount} uses per customer.
        slots:
          name: requestBody.name
          maxPersonalUsageCount: requestBody.maxPersonalUsageCount
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete promotions
      effect: destructive
      questions:
      - How do I permanently remove old promotions?
      - Can I delete several promotions at once?
      instructions:
      - text: Delete promotions {ids}.
        slots:
          ids: query.ids
      - text: Remove the promotions with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/coupons/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search coupon codes
      effect: read
      questions:
      - Which coupon codes belong to a given promotion?
      - Can I look up whether a specific coupon code exists?
      instructions:
      - text: List coupons for promotion {promotionId}.
        slots:
          promotionId: requestBody.promotionId
      - text: Find the coupon with code {code}.
        slots:
          code: requestBody.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/coupons/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a coupon by ID
      effect: read
      questions:
      - What details are stored for one coupon record?
      - Where do I read a single coupon by its ID?
      instructions:
      - text: Get coupon {id}.
        slots:
          id: path.id
      - text: Show the coupon record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/coupons/add'].post
  update:
    x-apievangelist-phrasing:
      intent: Add coupons to promotions
      effect: write
      questions:
      - How do I attach a set of new coupon codes to a promotion?
      - Can I add many coupons in one request?
      instructions:
      - text: Add these coupon codes.
      - text: Save this list of new coupons for my promotion.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/coupons/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete coupons
      effect: destructive
      questions:
      - How do I remove coupon codes I issued by mistake?
      - Can several coupons be deleted together?
      instructions:
      - text: Delete coupons {ids}.
        slots:
          ids: query.ids
      - text: Remove the coupon records {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/marketing/promotions/coupons/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import coupons from a file
      effect: write
      questions:
      - Can I bulk load coupon codes from a CSV file?
      - Is it possible to set an expiration date on coupons during an import?
      instructions:
      - text: Import coupons from {fileUrl} into promotion {promotionId}.
        slots:
          fileUrl: requestBody.fileUrl
          promotionId: requestBody.promotionId
      - text: Import coupons from {fileUrl} using delimiter {delimiter}, expiring on {expirationDate}.
        slots:
          fileUrl: requestBody.fileUrl
          delimiter: requestBody.delimiter
          expirationDate: requestBody.expirationDate
      method: generated
      generated: '2026-09-26'