# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Openmercantil Billing API
  version: 1.0.0
extends: openapi/openmercantil-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: 8
- target: $.paths['/api/v1/donation'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a one-time donation checkout
      effect: write
      questions:
      - Can I make a one-off donation to support OpenMercantil?
      - Do I need an account to donate?
      instructions:
      - text: Start a donation checkout for {amount_cents} cents.
        slots:
          amount_cents: requestBody.amount_cents
      - text: Donate {amount_cents} cents with the message {message}.
        slots:
          amount_cents: requestBody.amount_cents
          message: requestBody.message
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/credits/checkout'].post
  update:
    x-apievangelist-phrasing:
      intent: Buy a credit pack
      effect: write
      questions:
      - How do I buy more credits for company reports?
      - Is it safe to retry a credit pack purchase without being charged twice?
      instructions:
      - text: Buy the {pack} credit pack.
        slots:
          pack: requestBody.pack
      - text: Open a checkout for credit pack {pack}.
        slots:
          pack: requestBody.pack
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/checkout'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a subscription checkout
      effect: write
      questions:
      - How do I subscribe to a paid plan?
      - Can I choose annual billing or apply a coupon when subscribing?
      instructions:
      - text: Subscribe me to the {plan} plan.
        slots:
          plan: requestBody.plan
      - text: Start a {billing} checkout for the {plan} plan with coupon {coupon}.
        slots:
          billing: requestBody.billing
          plan: requestBody.plan
          coupon: requestBody.coupon
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billing/invoices'].get
  update:
    x-apievangelist-phrasing:
      intent: List my invoices and subscription
      effect: read
      questions:
      - Where can I see my past invoices?
      - What is the status of my current subscription?
      instructions:
      - text: List my invoices.
      - text: Show my billing history and current subscription.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billing/portal'].get
  update:
    x-apievangelist-phrasing:
      intent: Open my billing portal by redirect
      effect: read
      questions:
      - Can I be redirected straight to my Stripe billing portal?
      - Which link takes me to manage my payment method in the browser?
      instructions:
      - text: Redirect me to my Stripe billing portal.
      - text: Open the billing portal page in my browser.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billing/portal'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a billing portal session as JSON
      effect: write
      questions:
      - How do I get a Stripe customer portal URL returned as JSON?
      - What token do I need to create a billing portal session?
      instructions:
      - text: Create a billing portal session using CSRF token {csrf_token}.
        slots:
          csrf_token: header.X-CSRF-Token
      - text: Return a JSON link to my Stripe customer portal.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portal'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a portal session via the legacy route
      effect: write
      questions:
      - Does the old /api/v1/portal route still create a customer portal session?
      - Can I send the CSRF token as a form field on the legacy portal route?
      instructions:
      - text: Create a customer portal session through the legacy portal alias.
      - text: Open the Stripe portal via the deprecated route with form token {csrf}.
        slots:
          csrf: requestBody.csrf
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stripe-webhook'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive a signed Stripe event
      effect: write
      questions:
      - Where does Stripe deliver its signed events for OpenMercantil billing?
      - What happens when the same Stripe event is delivered twice?
      instructions:
      - text: Deliver Stripe event {id} of type {type}.
        slots:
          id: requestBody.id
          type: requestBody.type
      - text: Post signed Stripe event {id} to the billing webhook.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'