API Evangelist conversational phrasing for Scope3 Buyer Billing API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Scope3 Buyer Billing API
  version: 1.0.0
extends: openapi/scope3-buyer-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: 15
- target: $.paths['/billing/info'].get
  update:
    x-apievangelist-phrasing:
      intent: View invoice billing details
      effect: read
      questions:
      - Which contact, address and tax ID do my invoices go to?
      - Who receives copies of our invoices by email?
      instructions:
      - text: Show the billing contact and address my invoices are issued to.
      - text: Get my invoice billing details including tax ID.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/info'].put
  update:
    x-apievangelist-phrasing:
      intent: Update invoice billing details
      effect: write
      questions:
      - What's the minimum billing information needed before an invoice can be issued?
      - Can I add CC recipients for invoice emails?
      instructions:
      - text: Set my invoice billing contact to {contact_name} at {email}.
        slots:
          contact_name: requestBody.contactName
          email: requestBody.email
      - text: Update my billing address to {address}, {city} {postal_code}, {country} and tax ID {tax_id}.
        slots:
          address: requestBody.address
          city: requestBody.city
          postal_code: requestBody.postalCode
          country: requestBody.countryAlpha2
          tax_id: requestBody.taxId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/account'].get
  update:
    x-apievangelist-phrasing:
      intent: View my organization's commercial account summary
      effect: read
      questions:
      - What plan, pricing and credit balance is my organization on?
      - Is there anything I need to do to keep our account paid?
      - How much intelligence usage have we consumed this period?
      instructions:
      - text: Show my organization's billing account overview.
      - text: Tell me the next action needed on my billing account.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/iu-rate-card'].get
  update:
    x-apievangelist-phrasing:
      intent: View the IU rate card offer
      effect: read
      questions:
      - What IU plan is my organization being offered and has it been accepted?
      - What rollover policy applies to unused intelligence units?
      instructions:
      - text: Show my organization's IU rate card offer.
      - text: Get the IU plan list and net prices plus our acceptance record.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/iu-rate-card/v2'].get
  update:
    x-apievangelist-phrasing:
      intent: View the versioned enterprise IU offer document
      effect: read
      questions:
      - Where do I find the full enterprise IU proposal with payment options and support terms?
      - Can I see the activity schedule snapshot in the versioned IU commercial document?
      instructions:
      - text: Get the v2 enterprise IU commercial document.
      - text: Show the expanded IU offer with entitlements and payment options from the versioned endpoint.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/iu-rate-card/document.pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the Commercial Offer PDF
      effect: read
      questions:
      - Can I download our Commercial Offer proposal as a PDF?
      - Do I need a binding id or an offer version to fetch the proposal PDF?
      instructions:
      - text: Download the Commercial Offer PDF for offer version {offer_version}.
        slots:
          offer_version: query.offerVersion
      - text: Get the proposal PDF for binding {binding_id}.
        slots:
          binding_id: query.bindingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/iu-rate-card/accept'].post
  update:
    x-apievangelist-phrasing:
      intent: Accept an IU rate card plan
      effect: write
      questions:
      - How does an org admin accept the IU plan we were offered?
      - What if the IU offer changed between reviewing and accepting it?
      instructions:
      - text: Accept IU 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: Commit to IU plan {plan_id}, offer {offer_version}, payment option {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/payment-methods/setup'].post
  update:
    x-apievangelist-phrasing:
      intent: Start adding a payment card
      effect: write
      questions:
      - How do I add a credit card for my organization to pay with?
      - What does the embedded card form need to be mounted?
      instructions:
      - text: Start a card capture session so I can add a payment card.
      - text: Get a client secret to mount the card form for my organization.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/payment-methods'].get
  update:
    x-apievangelist-phrasing:
      intent: List saved payment methods
      effect: read
      questions:
      - Which card is on file for my organization and when does it expire?
      - Can I see the last four digits of our saved card?
      instructions:
      - text: List my organization's payment methods.
      - text: Show the brand and expiry of the card on file.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/payment-methods/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a saved payment method
      effect: destructive
      questions:
      - Can I delete our only payment card?
      - How do I remove an old card from my organization?
      instructions:
      - text: Remove payment method {id}.
        slots:
          id: path.id
      - text: Delete saved card {id} from my organization.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/capture-links/{token}'].get
  update:
    x-apievangelist-phrasing:
      intent: Open a one-time card capture link
      effect: read
      questions:
      - How long is a payment capture link valid?
      - Does a cardholder need an API key to open a card capture link?
      instructions:
      - text: Open payment capture link {token}.
        slots:
          token: path.token
      - text: Exchange capture token {token} with view {view}.
        slots:
          token: path.token
          view: query.view
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/payment-methods/pay-now'].post
  update:
    x-apievangelist-phrasing:
      intent: Retry a failed charge now
      effect: write
      questions:
      - Our last charge failed — can I retry it on the saved card right away?
      - How do I know a manual payment retry actually cleared the hold?
      instructions:
      - text: Retry my outstanding failed charge now.
      - text: Re-attempt the failed payment on the card on file.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/invoice-activity'].get
  update:
    x-apievangelist-phrasing:
      intent: View invoice activity
      effect: read
      questions:
      - Which of our invoices are paid and which are still due?
      - Why is my invoice activity empty?
      instructions:
      - text: Show my invoice activity.
      - text: Get invoice status and amounts for customer {customer_id}.
        slots:
          customer_id: query.targetCustomerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/fee-invoices'].get
  update:
    x-apievangelist-phrasing:
      intent: List IU fee invoices
      effect: read
      questions:
      - Can I list every IU fee invoice we've been issued, newest first?
      - Is there one fee invoice per billing cycle?
      instructions:
      - text: List my IU fee invoices.
      - text: List the fee invoices for customer {customer_id}.
        slots:
          customer_id: query.targetCustomerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/fee-invoices/{invoiceNumber}'].get
  update:
    x-apievangelist-phrasing:
      intent: View one fee invoice with line items
      effect: read
      questions:
      - What overage charges are on a specific fee invoice?
      - Can I see payments applied to an invoice by its number?
      instructions:
      - text: Show fee invoice {invoice_number}.
        slots:
          invoice_number: path.invoiceNumber
      - text: Get the line items on invoice {invoice_number}.
        slots:
          invoice_number: path.invoiceNumber
      method: generated
      generated: '2026-10-01'