# 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 Media Billing API
  version: 1.0.0
extends: openapi/scope3-media-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: 8
- target: $.paths['/billing/media-entities'].get
  update:
    x-apievangelist-phrasing:
      intent: List media billing entities
      effect: read
      questions:
      - Which legal entities does Scope3 invoice for our media spend?
      - Which of our billing entities is the primary one?
      instructions:
      - text: List our media billing entities.
      - text: Show the legal entities we're invoiced under for media.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/media-entities'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a media billing entity
      effect: write
      questions:
      - How do I add a new legal entity to be invoiced for media?
      - Does the first billing entity I create automatically become primary?
      instructions:
      - text: Create media billing entity {entityName} in {countryCode} billed in {currency}, emails {billingEmails}, at {addressLine1}, {city} {postalCode}.
        slots:
          entityName: requestBody.entityName
          countryCode: requestBody.countryCode
          currency: requestBody.currency
          billingEmails: requestBody.billingEmails
          addressLine1: requestBody.addressLine1
          city: requestBody.city
          postalCode: requestBody.postalCode
      - text: Add billing entity {entityName} ({countryCode}, {currency}) with tax ID {taxId}, invoices to {billingEmails}, {addressLine1}, {city} {postalCode}.
        slots:
          entityName: requestBody.entityName
          countryCode: requestBody.countryCode
          currency: requestBody.currency
          taxId: requestBody.taxId
          billingEmails: requestBody.billingEmails
          addressLine1: requestBody.addressLine1
          city: requestBody.city
          postalCode: requestBody.postalCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/media-entities/{entityId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a media billing entity
      effect: write
      questions:
      - Can I change the billing emails or address on an existing entity?
      - How do I make a different entity the primary one?
      instructions:
      - text: Change the billing emails on entity {entityId} to {billingEmails}.
        slots:
          entityId: path.entityId
          billingEmails: requestBody.billingEmails
      - text: 'Promote billing entity {entityId} to primary: {isPrimary}.'
        slots:
          entityId: path.entityId
          isPrimary: requestBody.isPrimary
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/media-entities/{entityId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a media billing entity
      effect: destructive
      questions:
      - Why can't I delete a billing entity that still has attachments?
      - What happens if I delete our primary billing entity?
      instructions:
      - text: Delete media billing entity {entityId}.
        slots:
          entityId: path.entityId
      - text: Remove billing entity {entityId} from our org.
        slots:
          entityId: path.entityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/media-entities/attachments'].get
  update:
    x-apievangelist-phrasing:
      intent: List media billing attachments
      effect: read
      questions:
      - Which advertisers and accounts are attached to which billing entity?
      - Can I see how our media invoices are routed?
      instructions:
      - text: List our media billing attachments.
      - text: Show which advertisers are attached to billing entities.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/media-entities/attachments'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a billing entity to an advertiser or account
      effect: write
      questions:
      - How do I bill one advertiser to a different legal entity?
      - Can I attach a billing entity to a child account instead of an advertiser?
      instructions:
      - text: Attach billing entity {entityId} to advertiser {advertiserId}.
        slots:
          entityId: requestBody.entityId
          advertiserId: requestBody.advertiserId
      - text: Route child account {childCustomerId} invoices to billing entity {entityId}.
        slots:
          childCustomerId: requestBody.childCustomerId
          entityId: requestBody.entityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/media-entities/attachments/{attachmentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a media billing attachment
      effect: destructive
      questions:
      - Can I detach an advertiser from its billing entity?
      - Who is allowed to remove a billing attachment?
      instructions:
      - text: Delete media billing attachment {attachmentId}.
        slots:
          attachmentId: path.attachmentId
      - text: Detach billing attachment {attachmentId}.
        slots:
          attachmentId: path.attachmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/billing/media-entities/resolve'].get
  update:
    x-apievangelist-phrasing:
      intent: Find who gets invoiced for an advertiser
      effect: read
      questions:
      - Which legal entity will be invoiced for this advertiser's media?
      - If an account has no attachment, does billing fall back to the primary entity?
      instructions:
      - text: Resolve the billing entity for advertiser {advertiserId}.
        slots:
          advertiserId: query.advertiserId
      - text: Tell me who gets the invoice for child account {childCustomerId}.
        slots:
          childCustomerId: query.childCustomerId
      method: generated
      generated: '2026-10-01'