API Evangelist conversational phrasing for Analytics Aggregated sales API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Analytics Aggregated sales API
  version: 1.0.0
extends: openapi/toast-aggregated-sales-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 4
- target: $.paths['/metrics'].post
  update:
    x-apievangelist-phrasing:
      intent: Request aggregated sales for a custom date range
      effect: write
      questions:
      - How do I request aggregated sales totals across my restaurants for an arbitrary span of business dates?
      - Can I pull sales metrics only for restaurants that are inactive?
      - Which restaurants can I exclude when building a custom-range sales metrics report?
      instructions:
      - text: Start an aggregated sales report from {start} to {end} for restaurants {restaurants}.
        slots:
          start: requestBody.startBusinessDate
          end: requestBody.endBusinessDate
          restaurants: requestBody.restaurantIds
      - text: Request custom-range sales metrics from {start} to {end}, grouped by {group_by}.
        slots:
          start: requestBody.startBusinessDate
          end: requestBody.endBusinessDate
          group_by: requestBody.groupBy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metrics/{timeRange}'].post
  update:
    x-apievangelist-phrasing:
      intent: Request aggregated sales for a preset time range
      effect: write
      questions:
      - Can I request daily or weekly sales metrics using a preset time range instead of custom dates?
      - What aggregation options exist when I ask for sales metrics by a fixed period like a day?
      - Is it possible to get sales metrics for a time range like a week and aggregate them by day?
      instructions:
      - text: Request {time_range} sales metrics from {start} to {end} for restaurants {restaurants}.
        slots:
          time_range: path.timeRange
          start: requestBody.startBusinessDate
          end: requestBody.endBusinessDate
          restaurants: requestBody.restaurantIds
      - text: Create a {time_range} sales metrics request aggregated by {aggregate_by}.
        slots:
          time_range: path.timeRange
          aggregate_by: query.aggregateBy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metrics/{reportRequestGuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch the results of a sales metrics report
      effect: read
      questions:
      - How do I download the aggregated sales numbers once my metrics report request is ready?
      - Can the sales metrics results include the guest-facing restaurant names?
      instructions:
      - text: Get the sales metrics results for report request {report}.
        slots:
          report: path.reportRequestGuid
      - text: Fetch sales metrics for report {report} with restaurant names included.
        slots:
          report: path.reportRequestGuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metrics/{timeRange}/{reportRequestGuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch sales metrics via the deprecated time-range path
      effect: read
      questions:
      - Is there an older endpoint that returns sales metrics results using both the time range and the report GUID?
      - What replaced the deprecated time-range sales metrics results endpoint?
      instructions:
      - text: Use the deprecated time-range endpoint to get {time_range} sales metrics for report {report}.
        slots:
          time_range: path.timeRange
          report: path.reportRequestGuid
      - text: Pull legacy {time_range} sales metrics for request {report} with restaurant names.
        slots:
          time_range: path.timeRange
          report: path.reportRequestGuid
      method: generated
      generated: '2026-10-01'