API Evangelist conversational phrasing for Admin API V1 Promotions API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Promotions API
  version: 1.0.0
extends: openapi/optimizely-promotions-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: 16
- target: $.paths['/api/v1/admin/Promotions'].get
  update:
    x-apievangelist-phrasing:
      intent: List promotions
      effect: read
      questions:
      - Which promotions are set up in the commerce admin?
      - Can I filter the promotions list to only live ones?
      - How many promotions exist in total?
      instructions:
      - text: List all promotions.
      - text: Find promotions matching {filter}.
        slots:
          filter: query.$filter
      - text: Show the top {top} promotions ordered by {orderby}.
        slots:
          top: query.$top
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Promotions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a promotion
      effect: write
      questions:
      - How do I set up a new promotion with a promo code?
      - What's required to add a promotion, like name, display message and code?
      instructions:
      - text: Create promotion {name} with promo code {promoCode} and message {displayMessage}.
        slots:
          name: requestBody.name
          promoCode: requestBody.promoCode
          displayMessage: requestBody.displayMessage
      - text: Add a promotion {name} that activates on {activateOn}.
        slots:
          name: requestBody.name
          activateOn: requestBody.activateOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Promotions({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a promotion
      effect: read
      questions:
      - Can I pull up one promotion's details by its ID?
      - What are the activation dates and code for a particular promotion?
      instructions:
      - text: Show promotion {id}.
        slots:
          id: path.id
      - text: Get promotion {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Promotions({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a promotion
      effect: write
      questions:
      - How do I overwrite a promotion record completely?
      - Does a full replace of a promotion need the name, code and description again?
      instructions:
      - text: Replace promotion {id} with a full record named {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Overwrite promotion {id} entirely using promo code {promoCode}.
        slots:
          id: path.id
          promoCode: requestBody.promoCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Promotions({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a promotion
      effect: destructive
      questions:
      - How do I permanently delete one promotion?
      - Can a promotion delete be guarded by an ETag check?
      instructions:
      - text: Delete promotion {id}.
        slots:
          id: path.id
      - text: Delete promotion {id} if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Promotions({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update fields on a promotion
      effect: write
      questions:
      - Can I change just the deactivation date of a promotion?
      - Is it possible to toggle a promotion live without resending everything?
      instructions:
      - text: Set promotion {id} to deactivate on {deactivateOn}.
        slots:
          id: path.id
          deactivateOn: requestBody.deactivateOn
      - text: Mark promotion {id} live status as {isLive}.
        slots:
          id: path.id
          isLive: requestBody.isLive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Promotions/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new promotion
      effect: read
      questions:
      - What defaults does a newly created promotion start with?
      - Is there a blank promotion template to prefill a form?
      instructions:
      - text: Get the default promotion template.
      - text: Show prefilled defaults for a new promotion.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Promotions/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive promotions via OData action
      effect: write
      questions:
      - Can I archive a batch of promotions with the OData archive action?
      - How do I retire promotions without deleting them, using a POST call?
      instructions:
      - text: Archive promotions {ids} using the Default.archive action.
        slots:
          ids: query.ids
      - text: Run the archive action on promotions {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Promotions({id})/Default.results'].post
  update:
    x-apievangelist-phrasing:
      intent: Set results on a promotion via OData action
      effect: write
      questions:
      - How do I define what a promotion awards, like a discount result, through the OData action?
      - Can I post promotion results to a promotion by its ID?
      instructions:
      - text: Set the results of promotion {id} to {promotionResults} using the Default.results action.
        slots:
          id: path.id
          promotionResults: requestBody.promotionResults
      - text: Post promotion results for promotion {id} through the OData action.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/promotions({key})/results'].post
  update:
    x-apievangelist-phrasing:
      intent: Set results on a promotion via route
      effect: write
      questions:
      - Is there a plain /results route to set a promotion's results by key?
      - Can I update what a promotion awards using the key-based results path?
      instructions:
      - text: Set results for promotion {key} through the /results route.
        slots:
          key: path.key
      - text: Post to the results path of promotion {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/promotions/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive promotions via route
      effect: destructive
      questions:
      - Can I archive promotions with a DELETE to the archive route?
      - Which call archives several promotions by ID using the archive path?
      instructions:
      - text: Archive promotions {ids} through the /archive route.
        slots:
          ids: query.ids
      - text: Send promotions {ids} to archive with the DELETE archive endpoint.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/promotions/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete promotions
      effect: destructive
      questions:
      - Can I permanently delete several promotions at once?
      - How do I bulk remove promotions by listing IDs?
      instructions:
      - text: Bulk delete promotions {ids}.
        slots:
          ids: query.ids
      - text: Permanently remove the promotions with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/promotions({key})/customerorderpromotions({customerorderpromotionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order where a promotion was applied
      effect: read
      questions:
      - Can I see a specific customer order application of a promotion?
      - Which order record shows a promotion being used?
      instructions:
      - text: Show order application {orderPromotion} of promotion {key}.
        slots:
          orderPromotion: path.customerorderpromotionKey
          key: path.key
      - text: Get customer order promotion {orderPromotion} under promotion {key}.
        slots:
          orderPromotion: path.customerorderpromotionKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/promotions({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a promotion
      effect: read
      questions:
      - Can I read a custom property stored on a promotion?
      - Where do extra custom fields for a promotion live?
      instructions:
      - text: Show custom property {property} on promotion {key}.
        slots:
          property: path.custompropertyKey
          key: path.key
      - text: Get promotion {key}'s custom field {property}.
        slots:
          property: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/promotions({key})/promotionresults({promotionresultKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a result of a promotion
      effect: read
      questions:
      - What does a particular result of a promotion award?
      - Can I look up a single promotion result record?
      instructions:
      - text: Show result {result} of promotion {key}.
        slots:
          result: path.promotionresultKey
          key: path.key
      - text: Get promotion result {result} for promotion {key}.
        slots:
          result: path.promotionresultKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/promotions({key})/websites({websiteKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a website a promotion runs on
      effect: read
      questions:
      - Which website is a promotion assigned to?
      - Can I view one website linked to a promotion?
      instructions:
      - text: Show website {website} linked to promotion {key}.
        slots:
          website: path.websiteKey
          key: path.key
      - text: Get the site {website} where promotion {key} runs.
        slots:
          website: path.websiteKey
          key: path.key
      method: generated
      generated: '2026-09-26'