API Evangelist conversational phrasing for stax-api Merchant API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for stax-api Merchant API
  version: 1.0.0
extends: openapi/stax-merchant-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: 11
- target: $.paths['/merchant/{id}/registration/file'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file to a merchant's registration
      effect: write
      questions:
      - Can I attach a voided check or ID document to a merchant's onboarding registration?
      - Is it possible to link an uploaded file to a specific registration document requirement?
      instructions:
      - text: Upload {file} named {name} to the registration of merchant {id}.
        slots:
          file: requestBody.file
          name: requestBody.name
          id: path.id
      - text: Attach {file} as {name} to merchant {id}'s registration document {registration_document_id}.
        slots:
          file: requestBody.file
          name: requestBody.name
          id: path.id
          registration_document_id: requestBody.registration_document_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter merchants
      effect: read
      questions:
      - Which merchants do I manage, and what status is each in?
      - Can I find merchants that are on a risk hold?
      - Is there a way to search my merchants by company name or contact email?
      instructions:
      - text: List all of my merchants.
      - text: Find merchants whose company name is {company_name}.
        slots:
          company_name: query.company_name
      - text: Show merchants with status {statuses}, {per_page} per page.
        slots:
          statuses: query.statuses[]
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a merchant
      effect: write
      questions:
      - How do I create a new merchant account on its own, without a user or registration?
      - Can I set the currency and reference when creating a merchant?
      instructions:
      - text: Create a merchant for {company_name} with contact {contact_name} at {contact_email}.
        slots:
          company_name: requestBody.company_name
          contact_name: requestBody.contact_name
          contact_email: requestBody.contact_email
      - text: Create merchant {company_name} using currency {currency} and reference {reference}.
        slots:
          company_name: requestBody.company_name
          currency: requestBody.currency
          reference: requestBody.reference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant/{id}/apikey'].get
  update:
    x-apievangelist-phrasing:
      intent: List a merchant's API keys
      effect: read
      questions:
      - Which API keys exist for one of my merchants?
      - Can I audit the API keys issued to a particular merchant account?
      instructions:
      - text: List the API keys for merchant {id}.
        slots:
          id: path.id
      - text: Show every API key issued to merchant {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant/{id}/apikey'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an API key for a merchant
      effect: write
      questions:
      - Can I generate a new API key on behalf of a merchant I manage?
      - Is it possible to give a new merchant API key a name and team role?
      instructions:
      - text: Generate a new API key for merchant {id}.
        slots:
          id: path.id
      - text: Create an API key named {name} with role {team_role} for merchant {id}.
        slots:
          name: requestBody.name
          team_role: requestBody.team_role
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant/{id}/registration/file/{file_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a file from a merchant's registration
      effect: destructive
      questions:
      - Can I delete a wrong document uploaded to a merchant's onboarding registration?
      - What happens if I remove a registration file from a merchant?
      instructions:
      - text: Delete file {file_id} from merchant {id}'s registration.
        slots:
          file_id: path.file_id
          id: path.id
      - text: Remove registration file {file_id} for merchant {id}.
        slots:
          file_id: path.file_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant/{merchant_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a merchant
      effect: read
      questions:
      - What details does Stax hold for one specific merchant account?
      - Can I look up a merchant's status and contact info by ID?
      instructions:
      - text: Get merchant {merchant_id}.
        slots:
          merchant_id: path.merchant_id
      - text: Show the status and contact details of merchant {merchant_id}.
        slots:
          merchant_id: path.merchant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant/{id}/registration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a merchant's registration data
      effect: read
      questions:
      - What onboarding information has a merchant submitted for underwriting?
      - Can I review the business and bank details on a merchant's registration?
      instructions:
      - text: Get the registration data for merchant {id}.
        slots:
          id: path.id
      - text: Show the underwriting registration details merchant {id} submitted.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant/{id}/registration'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a merchant's registration data
      effect: write
      questions:
      - Can I fill in a merchant's business legal name and tax ID for onboarding?
      - Is it possible to update the bank account a merchant registered with?
      - Can I set a merchant's expected annual volume and average ticket on their registration?
      instructions:
      - text: Set merchant {id}'s registration legal name to {business_legal_name} and tax ID to {business_tax_id}.
        slots:
          id: path.id
          business_legal_name: requestBody.business_legal_name
          business_tax_id: requestBody.business_tax_id
      - text: Update merchant {id}'s registration bank routing {bank_routing_number} and account {bank_account_number}.
        slots:
          id: path.id
          bank_routing_number: requestBody.bank_routing_number
          bank_account_number: requestBody.bank_account_number
      - text: Record annual volume {annual_volume} and average ticket {avg_trans_size} on merchant {id}'s registration.
        slots:
          annual_volume: requestBody.annual_volume
          avg_trans_size: requestBody.avg_trans_size
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant/{merchant_id}/user/{user_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Link an existing user to a merchant
      effect: write
      questions:
      - Can I give an existing Stax user access to another merchant account?
      - Is it possible to make a linked user the merchant admin or their default merchant?
      instructions:
      - text: Link user {user_id} to merchant {merchant_id}.
        slots:
          user_id: path.user_id
          merchant_id: path.merchant_id
      - text: 'Link user {user_id} to merchant {merchant_id} as merchant admin: {merchant_admin}.'
        slots:
          user_id: path.user_id
          merchant_id: path.merchant_id
          merchant_admin: query.merchant_admin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/merchant/{merchant_id}/user/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a user from a merchant
      effect: destructive
      questions:
      - Can I revoke a user's access to one merchant account without deleting the user?
      - What does unlinking a user from a merchant do?
      instructions:
      - text: Unlink user {user_id} from merchant {merchant_id}.
        slots:
          user_id: path.user_id
          merchant_id: path.merchant_id
      - text: Remove user {user_id}'s access to merchant {merchant_id}.
        slots:
          user_id: path.user_id
          merchant_id: path.merchant_id
      method: generated
      generated: '2026-09-26'