# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reference Tiers API
  version: 1.0.0
extends: openapi/beehiiv-tiers-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: 5
- target: $.paths['/publications/{publicationId}/tiers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a publication's subscription tiers
      effect: read
      questions:
      - What paid tiers does my newsletter offer?
      - Can I see my tiers along with their prices?
      instructions:
      - text: List subscription tiers on publication {publication}.
        slots:
          publication: path.publicationId
      - text: Show the paid tiers on {publication} with {expand} expanded.
        slots:
          publication: path.publicationId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/tiers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a subscription tier
      effect: write
      questions:
      - How do I add a new paid tier to my newsletter?
      - Can I set prices when creating a tier?
      instructions:
      - text: Create a tier named {name} on publication {publication}.
        slots:
          name: requestBody.name
          publication: path.publicationId
      - text: Create tier {name} with prices {prices_attributes}.
        slots:
          name: requestBody.name
          prices_attributes: requestBody.prices_attributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/tiers/{tierId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one subscription tier
      effect: read
      questions:
      - What's included in a specific tier and what does it cost?
      - Can I retrieve a single tier by its ID?
      instructions:
      - text: Get tier {tier} on publication {publication}.
        slots:
          tier: path.tierId
          publication: path.publicationId
      - text: Show what tier {tier} includes and costs.
        slots:
          tier: path.tierId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/tiers/{tierId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a subscription tier (PUT)
      effect: write
      questions:
      - How do I PUT a new name or description onto an existing tier?
      - Can I replace a tier's prices with a PUT request?
      instructions:
      - text: PUT name {name} on tier {tier} in publication {publication}.
        slots:
          name: requestBody.name
          tier: path.tierId
          publication: path.publicationId
      - text: Replace the prices of tier {tier} with {prices_attributes} via PUT.
        slots:
          tier: path.tierId
          prices_attributes: requestBody.prices_attributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/tiers/{tierId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a subscription tier (PATCH)
      effect: write
      questions:
      - Can I PATCH just the description of an existing tier?
      - What's the PATCH call for changing a tier's prices?
      instructions:
      - text: PATCH tier {tier} on {publication} with description {description}.
        slots:
          tier: path.tierId
          publication: path.publicationId
          description: requestBody.description
      - text: PATCH the prices on tier {tier} to {prices_attributes}.
        slots:
          tier: path.tierId
          prices_attributes: requestBody.prices_attributes
      method: generated
      generated: '2026-09-26'