# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Scope3 Storefront Storefront Billing API
  version: 1.0.0
extends: openapi/scope3-storefront-billing-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/billing/storefront-rate-card'].get
  update:
    x-apievangelist-phrasing:
      intent: View the storefront rate card offer
      effect: read
      questions:
      - What paid storefront plans am I being offered and at what net price?
      - Has my organization already accepted a storefront rate card?
      - Does my storefront offer include a corporate discount?
      instructions:
      - text: Show my storefront rate card offer and acceptance state.
      - text: Get the storefront plan prices and acceptance history for my organization.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/storefront-rate-card/accept'].post
  update:
    x-apievangelist-phrasing:
      intent: Accept a storefront rate card plan
      effect: write
      questions:
      - How do I accept a paid storefront plan from the rate card?
      - What happens if the storefront offer changed after I reviewed it?
      instructions:
      - text: Accept storefront plan {plan_id} on offer version {offer_version} with idempotency key {idempotency_key}.
        slots:
          plan_id: requestBody.planId
          offer_version: requestBody.offerVersion
          idempotency_key: requestBody.idempotencyKey
      - text: Sign up for storefront plan {plan_id}, offer {offer_version}, paying by {payment_option}, key {idempotency_key}.
        slots:
          plan_id: requestBody.planId
          offer_version: requestBody.offerVersion
          payment_option: requestBody.paymentOptionKey
          idempotency_key: requestBody.idempotencyKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/payout-activity'].get
  update:
    x-apievangelist-phrasing:
      intent: View storefront payout activity
      effect: read
      questions:
      - Have any payouts been paid to my storefront yet?
      - When is my next storefront payout expected?
      instructions:
      - text: Show my storefront payout activity.
      - text: Get payout activity for customer {customer_id}.
        slots:
          customer_id: query.targetCustomerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing'].get
  update:
    x-apievangelist-phrasing:
      intent: View storefront billing configuration
      effect: read
      questions:
      - What platform fee and payment terms apply to my storefront?
      - Is my storefront's payout setup complete?
      instructions:
      - text: Show my storefront billing configuration.
      - text: Get the billing config, fees and payout status for customer {customer_id}.
        slots:
          customer_id: query.targetCustomerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing'].put
  update:
    x-apievangelist-phrasing:
      intent: Change storefront fees, currency or net days
      effect: write
      questions:
      - Can I change the platform fee percentage on my storefront?
      - How do I set default net payment days for buyers?
      instructions:
      - text: Set my storefront platform fee to {percent} percent.
        slots:
          percent: requestBody.platformFeePercent
      - text: Change storefront billing currency to {currency} with net {net_days} payment terms.
        slots:
          currency: requestBody.currency
          net_days: requestBody.defaultNetDays
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/payout-details'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the default payout bank account
      effect: write
      questions:
      - Where do I enter the bank account my storefront gets paid out to?
      - Which bank identifiers are accepted for storefront bank transfers?
      instructions:
      - text: Set my default payout account to {beneficiary_name}, {address_line1}, {city} {postal_code}, {country_code}, {bank_id_type} {bank_id_value}, paid in {currency}.
        slots:
          beneficiary_name: requestBody.beneficiaryName
          address_line1: requestBody.addressLine1
          city: requestBody.city
          postal_code: requestBody.postalCode
          country_code: requestBody.countryCode
          bank_id_type: requestBody.bankIdentifierType
          bank_id_value: requestBody.bankIdentifierValue
          currency: requestBody.currency
      - text: Replace my storefront payout bank details with account {account_number} for {beneficiary_name}.
        slots:
          account_number: requestBody.accountNumber
          beneficiary_name: requestBody.beneficiaryName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/payees'].get
  update:
    x-apievangelist-phrasing:
      intent: List payout payees by legal entity
      effect: read
      questions:
      - Which legal entities have payout bank accounts on file?
      - Can I see the payee for each payout currency?
      instructions:
      - text: List my payout payees.
      - text: Show payout payees on file for customer {customer_id}.
        slots:
          customer_id: query.targetCustomerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/payees'].put
  update:
    x-apievangelist-phrasing:
      intent: Add or update a payee for one legal entity
      effect: write
      questions:
      - Can I pay out different legal entities to different bank accounts?
      - Can each entity have its own bank account per currency?
      instructions:
      - text: 'Set {entity}''s {currency} payee: {name}, {addr}, {city} {zip}, {country}, bank {id_type} {id_value}.'
        slots:
          currency: requestBody.currency
          entity: requestBody.entityName
          name: requestBody.beneficiaryName
          addr: requestBody.addressLine1
          city: requestBody.city
          zip: requestBody.postalCode
          country: requestBody.countryCode
          id_type: requestBody.bankIdentifierType
          id_value: requestBody.bankIdentifierValue
      - text: Make the payee for {entity_name} in {currency} the primary one ({is_primary}).
        slots:
          entity_name: requestBody.entityName
          currency: requestBody.currency
          is_primary: requestBody.isPrimary
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/accounts'].get
  update:
    x-apievangelist-phrasing:
      intent: List billing status of managed accounts
      effect: read
      questions:
      - What is the billing status of each account I manage?
      - Can a parent customer see billing for all its child accounts?
      instructions:
      - text: List billing status for all my managed accounts.
      - text: Show which of my child accounts have billing set up.
      method: generated
      generated: '2026-10-01'