# 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 Budget Calendars API
  version: 1.0.0
extends: openapi/optimizely-budget-calendars-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: 12
- target: $.paths['/api/v1/admin/BudgetCalendars'].get
  update:
    x-apievangelist-phrasing:
      intent: List budget calendars
      effect: read
      questions:
      - What fiscal-year budget calendars are set up for my B2B customers?
      - Can I filter budget calendars to one fiscal year or customer?
      instructions:
      - text: List all budget calendars.
      - text: List budget calendars where {filter}.
        slots:
          filter: query.$filter
      - text: Return budget calendars sorted by {orderby}, first {top} only.
        slots:
          orderby: query.$orderby
          top: query.$top
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/BudgetCalendars'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a budget calendar
      effect: write
      questions:
      - How do I define budget periods for a customer's fiscal year?
      - Can a budget calendar have up to thirteen periods?
      instructions:
      - text: Create a budget calendar for customer {customerId} in fiscal year {fiscalYear}.
        slots:
          customerId: requestBody.customerId
          fiscalYear: requestBody.fiscalYear
      - text: Add a {fiscalYear} budget calendar starting period one on {period1StartDate} and ending {fiscalYearEndDate}.
        slots:
          fiscalYear: requestBody.fiscalYear
          period1StartDate: requestBody.period1StartDate
          fiscalYearEndDate: requestBody.fiscalYearEndDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/BudgetCalendars({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a budget calendar by id
      effect: read
      questions:
      - When does each budget period start for a given budget calendar?
      - Can I look up one budget calendar record by id?
      instructions:
      - text: Get budget calendar {id}.
        slots:
          id: path.id
      - text: Fetch budget calendar {id} returning only {select}.
        slots:
          id: path.id
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/BudgetCalendars({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a budget calendar
      effect: write
      questions:
      - How do I overwrite every period date on a budget calendar at once?
      - What does a full replacement of a budget calendar need?
      instructions:
      - text: Replace budget calendar {id} with fiscal year {fiscalYear}.
        slots:
          id: path.id
          fiscalYear: requestBody.fiscalYear
      - text: Overwrite budget calendar {id} with fiscal year end {fiscalYearEndDate}.
        slots:
          id: path.id
          fiscalYearEndDate: requestBody.fiscalYearEndDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/BudgetCalendars({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a budget calendar
      effect: destructive
      questions:
      - Can I remove one budget calendar by its id?
      - Does deleting a budget calendar support an If-Match ETag?
      instructions:
      - text: Delete budget calendar {id}.
        slots:
          id: path.id
      - text: Delete budget calendar {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/BudgetCalendars({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update dates on a budget calendar
      effect: write
      questions:
      - How do I shift just one period's start date on a budget calendar?
      - Can I change a budget calendar's fiscal year end without resending all periods?
      instructions:
      - text: Move period 2 of budget calendar {id} to start on {period2StartDate}.
        slots:
          id: path.id
          period2StartDate: requestBody.period2StartDate
      - text: Set the fiscal year end of budget calendar {id} to {fiscalYearEndDate}.
        slots:
          id: path.id
          fiscalYearEndDate: requestBody.fiscalYearEndDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/BudgetCalendars/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank budget calendar template
      effect: read
      questions:
      - What default values does a new budget calendar start with?
      - Is there an empty budget calendar template to fill in?
      instructions:
      - text: Get the default budget calendar template.
      - text: Show the defaults for a new budget calendar.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/budgetcalendars/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete budget calendars
      effect: destructive
      questions:
      - Can I delete several budget calendars in one request?
      - How do I remove a list of budget calendars by id at once?
      instructions:
      - text: Bulk delete budget calendars {ids}.
        slots:
          ids: query.ids
      - text: Remove the budget calendars with ids {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/budgetcalendars({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property of a budget calendar
      effect: read
      questions:
      - What custom property values are stored on a budget calendar?
      - Can I read one extension field from a budget calendar?
      instructions:
      - text: Get custom property {custompropertyKey} of budget calendar {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Read custom field {custompropertyKey} on budget calendar {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/budgetcalendars'].get
  update:
    x-apievangelist-phrasing:
      intent: List budget calendars through the storefront API
      effect: read
      questions:
      - Which fiscal years have budget calendars set up for the signed-in customer?
      - Can the website API show me the budget periods defined for my account?
      instructions:
      - text: Show the storefront budget calendars for the current customer.
      - text: List every fiscal year budget calendar available through the website API.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/budgetcalendars/{fiscalYear}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the budget calendar for a fiscal year
      effect: read
      questions:
      - What budget periods are defined for a given fiscal year?
      - When does a particular fiscal year end in the budget calendar?
      instructions:
      - text: Get the budget calendar for fiscal year {fiscalYear}.
        slots:
          fiscalYear: path.fiscalYear
      - text: Show budget periods for fiscal year {fiscalYear}.
        slots:
          fiscalYear: path.fiscalYear
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/budgetcalendars/{fiscalYear}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a fiscal year's budget calendar
      effect: write
      questions:
      - How do I change the budget periods for a fiscal year?
      - Can I set the fiscal year end date on a budget calendar?
      instructions:
      - text: Set the end date of fiscal year {fiscalYear} to {fiscalYearEndDate}.
        slots:
          fiscalYear: path.fiscalYear
          fiscalYearEndDate: requestBody.fiscalYearEndDate
      - text: Update budget periods for fiscal year {fiscalYear} to {budgetPeriods}.
        slots:
          fiscalYear: path.fiscalYear
          budgetPeriods: requestBody.budgetPeriods
      method: generated
      generated: '2026-10-01'