# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Stripe Charges API
  version: 1.0.0
extends: openapi/stripe-charges-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: 14
- target: $.paths['/v1/charges'].get
  update:
    x-apievangelist-phrasing:
      intent: List charges
      effect: read
      questions:
      - How do I see all the charges I've made, newest first?
      - Can I list only the charges for one customer?
      - Which charges came from a specific PaymentIntent?
      instructions:
      - text: List my recent charges.
      - text: List charges for customer {customer}.
        slots:
          customer: query.customer
      - text: Show charges created in {created}.
        slots:
          created: query.created
      - text: List charges for PaymentIntent {payment_intent}.
        slots:
          payment_intent: query.payment_intent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges'].post
  update:
    x-apievangelist-phrasing:
      intent: Charge a card or payment source
      effect: write
      questions:
      - How do I charge a customer's saved card directly?
      - Can I authorize a charge now and capture it later?
      - Should I create charges directly or use PaymentIntents instead?
      instructions:
      - text: Charge customer {customer} {amount} {currency}.
        slots:
          customer: requestBody.customer
          amount: requestBody.amount
          currency: requestBody.currency
      - text: Charge {amount} {currency} to source {source} for {description}.
        slots:
          amount: requestBody.amount
          currency: requestBody.currency
          source: requestBody.source
          description: requestBody.description
      - text: 'Authorize {amount} {currency} on customer {customer} without capturing: {capture}.'
        slots:
          amount: requestBody.amount
          currency: requestBody.currency
          customer: requestBody.customer
          capture: requestBody.capture
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search charges
      effect: read
      questions:
      - How do I find charges matching an amount, status or metadata value?
      - Can I search charges right after creating one?
      instructions:
      - text: Search charges for {query}.
        slots:
          query: query.query
      - text: Find up to {limit} charges matching {query}.
        slots:
          limit: query.limit
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a charge
      effect: read
      questions:
      - How do I look up the details of one charge?
      - Did this charge succeed, and was it refunded?
      instructions:
      - text: Show charge {charge}.
        slots:
          charge: path.charge
      - text: Check the status of charge {charge}.
        slots:
          charge: path.charge
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a charge
      effect: write
      questions:
      - How do I change the description or receipt email on a charge?
      - Can I flag a charge as fraudulent after the fact?
      instructions:
      - text: Set the description of charge {charge} to {description}.
        slots:
          charge: path.charge
          description: requestBody.description
      - text: Send the receipt for charge {charge} to {receipt_email}.
        slots:
          charge: path.charge
          receipt_email: requestBody.receipt_email
      - text: Report charge {charge} with fraud details {fraud_details}.
        slots:
          charge: path.charge
          fraud_details: requestBody.fraud_details
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/capture'].post
  update:
    x-apievangelist-phrasing:
      intent: Capture an authorized charge
      effect: write
      questions:
      - How do I capture a charge I only authorized earlier?
      - Can I capture less than the full authorized amount?
      - How long do I have before an uncaptured charge expires?
      instructions:
      - text: Capture charge {charge}.
        slots:
          charge: path.charge
      - text: Capture {amount} of authorized charge {charge}.
        slots:
          amount: requestBody.amount
          charge: path.charge
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/dispute'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the dispute on a charge
      effect: read
      questions:
      - How do I see whether a customer disputed a specific charge?
      - What's the status of the chargeback on this charge?
      instructions:
      - text: Show the dispute on charge {charge}.
        slots:
          charge: path.charge
      - text: Check the chargeback status for charge {charge}.
        slots:
          charge: path.charge
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/dispute'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit evidence for a charge's dispute
      effect: write
      questions:
      - How do I respond to a chargeback on a specific charge?
      - Can I save dispute evidence without submitting it yet?
      instructions:
      - text: Add evidence {evidence} to the dispute on charge {charge}.
        slots:
          evidence: requestBody.evidence
          charge: path.charge
      - text: 'Submit evidence {evidence} for charge {charge} now: {submit}.'
        slots:
          evidence: requestBody.evidence
          charge: path.charge
          submit: requestBody.submit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/dispute/close'].post
  update:
    x-apievangelist-phrasing:
      intent: Accept the dispute on a charge
      effect: destructive
      questions:
      - How do I concede a chargeback on a charge I can't contest?
      - What happens if I close the dispute on a charge?
      instructions:
      - text: Close the dispute on charge {charge}.
        slots:
          charge: path.charge
      - text: Accept the chargeback on charge {charge} without evidence.
        slots:
          charge: path.charge
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund a charge
      effect: write
      questions:
      - How do I refund a charge that hasn't been refunded yet?
      - Can I still partially refund a charge through the older single-refund charge endpoint?
      - Can a refund also return the application fee?
      instructions:
      - text: Refund charge {charge} in full.
        slots:
          charge: path.charge
      - text: Refund {amount} of charge {charge} for reason {reason}.
        slots:
          amount: requestBody.amount
          charge: path.charge
          reason: requestBody.reason
      - text: 'Refund charge {charge} and reverse the transfer: {reverse_transfer}.'
        slots:
          charge: path.charge
          reverse_transfer: requestBody.reverse_transfer
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/refunds'].get
  update:
    x-apievangelist-phrasing:
      intent: List refunds on a charge
      effect: read
      questions:
      - How do I see every refund issued against one charge?
      - Can I page through refunds beyond the ten most recent on a charge?
      instructions:
      - text: List refunds for charge {charge}.
        slots:
          charge: path.charge
      - text: Show the last {limit} refunds on charge {charge}.
        slots:
          limit: query.limit
          charge: path.charge
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/refunds'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a refund on a charge
      effect: write
      questions:
      - How do I issue a new refund against a charge?
      - Can I refund part of a charge more than once until it's fully refunded?
      instructions:
      - text: Create a refund on charge {charge}.
        slots:
          charge: path.charge
      - text: Issue a {amount} refund on charge {charge} marked {reason}.
        slots:
          amount: requestBody.amount
          charge: path.charge
          reason: requestBody.reason
      - text: Refund charge {charge} and email instructions to {instructions_email}.
        slots:
          charge: path.charge
          instructions_email: requestBody.instructions_email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/refunds/{refund}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a refund on a charge
      effect: read
      questions:
      - How do I check the status of one refund on a charge?
      - Has this refund gone through yet?
      instructions:
      - text: Show refund {refund} on charge {charge}.
        slots:
          refund: path.refund
          charge: path.charge
      - text: Check whether refund {refund} for charge {charge} succeeded.
        slots:
          refund: path.refund
          charge: path.charge
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/charges/{charge}/refunds/{refund}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a refund on a charge
      effect: write
      questions:
      - How do I add my own notes to a refund?
      - What can I change on a refund after creating it?
      instructions:
      - text: Set metadata {metadata} on refund {refund} of charge {charge}.
        slots:
          metadata: requestBody.metadata
          refund: path.refund
          charge: path.charge
      - text: Tag refund {refund} on charge {charge} with {metadata}.
        slots:
          refund: path.refund
          charge: path.charge
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'