# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Hilt So Billing API
  version: 1.0.0
extends: openapi/hilt-so-billing-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['/v1/billing/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: View my billing summary
      effect: read
      questions:
      - What plan am I on and what's my current billing status?
      - Where can I see a summary of my Hilt subscription?
      instructions:
      - text: Show my billing summary.
      - text: Tell me which plan I'm currently billed for.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/billing/checkout/stripe'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a Stripe checkout to upgrade my plan
      effect: write
      questions:
      - How do I pay for a paid Hilt plan by card through Stripe?
      - Can I choose yearly instead of monthly billing when upgrading?
      instructions:
      - text: Start a Stripe checkout for the {plan} plan, returning to {success_url} or {cancel_url}.
        slots:
          plan: requestBody.plan
          success_url: requestBody.success_url
          cancel_url: requestBody.cancel_url
      - text: Upgrade me to {plan} billed {interval}, redirecting to {success_url} on success and {cancel_url} on cancel.
        slots:
          plan: requestBody.plan
          interval: requestBody.interval
          success_url: requestBody.success_url
          cancel_url: requestBody.cancel_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/billing/portal/stripe'].post
  update:
    x-apievangelist-phrasing:
      intent: Open the Stripe billing portal
      effect: write
      questions:
      - Where do I update my card or cancel my subscription?
      - Can I manage my invoices in a Stripe customer portal?
      instructions:
      - text: Open my Stripe billing portal and return me to {return_url}.
        slots:
          return_url: requestBody.return_url
      - text: Get me a billing portal link that comes back to {return_url}.
        slots:
          return_url: requestBody.return_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/billing/refresh/stripe'].post
  update:
    x-apievangelist-phrasing:
      intent: Resync my billing from Stripe
      effect: write
      questions:
      - My plan change isn't showing - can I force a resync from Stripe?
      - Is there a way to refresh my subscription state after paying?
      instructions:
      - text: Resync my billing status from Stripe.
      - text: Refresh my Stripe subscription state now.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/billing/webhooks/stripe'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive Stripe billing webhook events
      effect: write
      questions:
      - Which endpoint should Stripe send subscription webhooks to?
      - How are incoming Stripe billing events verified?
      instructions:
      - text: Deliver a Stripe billing event signed with {signature}.
        slots:
          signature: header.Stripe-Signature
      - text: Post this Stripe subscription webhook to the billing receiver.
      method: generated
      generated: '2026-09-26'