# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Loyalty Balance API
  version: 1.0.0
extends: openapi/brevo-balance-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: 18
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List balance definitions in a loyalty program
      effect: read
      questions:
      - Which point or credit balances are defined in my loyalty program?
      - Can I page through the balance definitions of a program sorted by a field?
      instructions:
      - text: List the balance definitions in loyalty program {pid}.
        slots:
          pid: path.pid
      - text: Show {limit} balance definitions for program {pid}.
        slots:
          limit: query.limit
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a balance definition
      effect: write
      questions:
      - How do I set up a new points balance with its own unit in a loyalty program?
      - Can I cap the maximum amount or set an expiration when defining a balance?
      instructions:
      - text: Create a balance definition named {name} measured in {unit} in program {pid}.
        slots:
          name: requestBody.name
          unit: requestBody.unit
          pid: path.pid
      - text: Define a new {unit} balance {name} in program {pid} with a max amount of {maxAmount}.
        slots:
          unit: requestBody.unit
          name: requestBody.name
          pid: path.pid
          maxAmount: requestBody.maxAmount
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions/{bdid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a balance definition
      effect: read
      questions:
      - What are the settings of one specific balance definition, like its unit and limits?
      - Can I read a balance definition as it stood in a particular program version?
      instructions:
      - text: Show balance definition {bdid} in program {pid}.
        slots:
          bdid: path.bdid
          pid: path.pid
      - text: Get balance definition {bdid} from program {pid} at version {version}.
        slots:
          bdid: path.bdid
          pid: path.pid
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions/{bdid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a balance definition
      effect: write
      questions:
      - Can I change the name, unit or rounding rules of an existing balance definition?
      - Is it possible to raise the credit limit on a balance I already defined?
      instructions:
      - text: Update balance definition {bdid} in program {pid} to name {name} and unit {unit}.
        slots:
          bdid: path.bdid
          pid: path.pid
          name: requestBody.name
          unit: requestBody.unit
      - text: Change the max credit limit of balance definition {bdid} in program {pid} to {maxCreditAmountLimit}, keeping name {name} and unit {unit}.
        slots:
          bdid: path.bdid
          pid: path.pid
          maxCreditAmountLimit: requestBody.maxCreditAmountLimit
          name: requestBody.name
          unit: requestBody.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions/{bdid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a balance definition
      effect: destructive
      questions:
      - Can I remove a balance definition from my loyalty program?
      - What do I need to delete a points balance type I no longer use?
      instructions:
      - text: Delete balance definition {bdid} from program {pid}.
        slots:
          bdid: path.bdid
          pid: path.pid
      - text: Remove the balance type {bdid} in loyalty program {pid}.
        slots:
          bdid: path.bdid
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions/{bdid}/limits'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a limit to a balance definition
      effect: write
      questions:
      - How do I cap how many points a member can earn per week?
      - Can a balance limit apply to credits, debits or use a sliding schedule?
      instructions:
      - text: Add a {transactionType} limit of {value} per {durationValue} {durationUnit} with constraint {constraintType} to balance {bdid} in program {pid}.
        slots:
          transactionType: requestBody.transactionType
          value: requestBody.value
          durationValue: requestBody.durationValue
          durationUnit: requestBody.durationUnit
          constraintType: requestBody.constraintType
          bdid: path.bdid
          pid: path.pid
      - text: Create a balance limit on definition {bdid} in program {pid}.
        slots:
          bdid: path.bdid
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions/{bdid}/limits/{blid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a balance limit
      effect: read
      questions:
      - What are the constraints of a specific limit on a balance definition?
      - Can I read a balance limit as of a given program version?
      instructions:
      - text: Show balance limit {blid} on definition {bdid} in program {pid}.
        slots:
          blid: path.blid
          bdid: path.bdid
          pid: path.pid
      - text: Get limit {blid} of balance {bdid} in program {pid} at version {version}.
        slots:
          blid: path.blid
          bdid: path.bdid
          pid: path.pid
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions/{bdid}/limits/{blid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a balance limit
      effect: write
      questions:
      - Can I change the value or duration of an existing balance limit?
      - Is it possible to switch a limit I already created to a sliding schedule?
      instructions:
      - text: Change balance limit {blid} on definition {bdid} in program {pid} to {value} per {durationValue} {durationUnit}.
        slots:
          blid: path.blid
          bdid: path.bdid
          pid: path.pid
          value: requestBody.value
          durationValue: requestBody.durationValue
          durationUnit: requestBody.durationUnit
      - text: Edit limit {blid} of balance {bdid} in program {pid}.
        slots:
          blid: path.blid
          bdid: path.bdid
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/balance-definitions/{bdid}/limits/{blid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a balance limit
      effect: destructive
      questions:
      - Can I remove an earning or spending cap from a balance?
      - What identifies the balance limit I want to delete?
      instructions:
      - text: Delete balance limit {blid} from definition {bdid} in program {pid}.
        slots:
          blid: path.blid
          bdid: path.bdid
          pid: path.pid
      - text: Remove limit {blid} on balance {bdid} of program {pid}.
        slots:
          blid: path.blid
          bdid: path.bdid
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/subscriptions/{cid}/balances'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a member's balances by subscription
      effect: read
      questions:
      - How many points does a specific loyalty member currently have?
      - Can I include internal balances when checking a member's subscription?
      instructions:
      - text: Show the balances for subscription {cid} in program {pid}.
        slots:
          cid: path.cid
          pid: path.pid
      - text: Get all balances, including internal ones, for member {cid} in program {pid}.
        slots:
          cid: path.cid
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/subscriptions/{cid}/balances'].post
  update:
    x-apievangelist-phrasing:
      intent: Open a balance for a member
      effect: write
      questions:
      - How do I give a loyalty member a new balance of a given type?
      - Can I create a balance for a contact that doesn't have one yet?
      instructions:
      - text: Create a balance of definition {balanceDefinitionId} for member {cid} in program {pid}.
        slots:
          balanceDefinitionId: requestBody.balanceDefinitionId
          cid: path.cid
          pid: path.pid
      - text: Open a {balanceDefinitionId} balance for subscription {cid} in program {pid}.
        slots:
          balanceDefinitionId: requestBody.balanceDefinitionId
          cid: path.cid
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/contact-balances'].get
  update:
    x-apievangelist-phrasing:
      intent: List all members' balances for one balance type
      effect: read
      questions:
      - Which members hold a given balance type, and how much does each one have?
      - Can I list contact balances for one balance definition across every subscription?
      instructions:
      - text: List contact balances for definition {balanceDefinitionId} in program {pid}.
        slots:
          balanceDefinitionId: query.balanceDefinitionId
          pid: path.pid
      - text: Show {limit} member balances of type {balanceDefinitionId} in program {pid}.
        slots:
          limit: query.limit
          balanceDefinitionId: query.balanceDefinitionId
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/transactions'].post
  update:
    x-apievangelist-phrasing:
      intent: Credit or debit a member's balance
      effect: write
      questions:
      - How do I award or deduct loyalty points for a contact?
      - Can a balance transaction complete automatically or expire after a TTL?
      instructions:
      - text: Create a transaction of {amount} on balance {balanceDefinitionId} for contact {contactId} in program {pid}.
        slots:
          amount: requestBody.amount
          balanceDefinitionId: requestBody.balanceDefinitionId
          contactId: requestBody.contactId
          pid: path.pid
      - text: Start an auto-completing {transactionType} of {amount} on balance {balanceDefinitionId} in program {pid}.
        slots:
          transactionType: requestBody.transactionType
          amount: requestBody.amount
          balanceDefinitionId: requestBody.balanceDefinitionId
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/transactions/{tid}/complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete a pending balance transaction
      effect: write
      questions:
      - How do I finalize a balance transaction I started earlier?
      - What confirms a pending points credit so it hits the member's balance?
      instructions:
      - text: Complete balance transaction {tid} in program {pid}.
        slots:
          tid: path.tid
          pid: path.pid
      - text: Finalize the pending transaction {tid} for program {pid}.
        slots:
          tid: path.tid
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/transactions/{tid}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a pending balance transaction
      effect: destructive
      questions:
      - Can I cancel a balance transaction before it's completed?
      - What undoes a points credit that is still pending?
      instructions:
      - text: Cancel balance transaction {tid} in program {pid}.
        slots:
          tid: path.tid
          pid: path.pid
      - text: Void the pending transaction {tid} in loyalty program {pid}.
        slots:
          tid: path.tid
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/create-order'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a balance order for a contact
      effect: write
      questions:
      - How do I schedule a balance credit for a contact that is due on a future date?
      - Can a balance order carry a source and expiration date?
      instructions:
      - text: Create a balance order of {amount} on {balanceDefinitionId} for contact {contactId}, due {dueAt}, source {source}, in program {pid}.
        slots:
          amount: requestBody.amount
          balanceDefinitionId: requestBody.balanceDefinitionId
          contactId: requestBody.contactId
          dueAt: requestBody.dueAt
          source: requestBody.source
          pid: path.pid
      - text: Place a balance order in program {pid} that expires at {expiresAt}.
        slots:
          pid: path.pid
          expiresAt: requestBody.expiresAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/active-balance'].get
  update:
    x-apievangelist-phrasing:
      intent: List a contact's active balances
      effect: read
      questions:
      - Which unexpired balance lots does a contact currently hold for one balance type?
      - Can I see a contact's active balances sorted by a field?
      instructions:
      - text: Show active balances of type {balanceDefinitionId} for contact {contactId} in program {pid}.
        slots:
          balanceDefinitionId: query.balanceDefinitionId
          contactId: query.contactId
          pid: path.pid
      - text: List {limit} currently active balances for contact {contactId} on definition {balanceDefinitionId} in program {pid}.
        slots:
          limit: query.limit
          contactId: query.contactId
          balanceDefinitionId: query.balanceDefinitionId
          pid: path.pid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/loyalty/balance/programs/{pid}/transaction-history'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact's balance transaction history
      effect: read
      questions:
      - What credits and debits have been made to a contact's balance over time?
      - Can I filter a member's transaction history by status or transaction type?
      instructions:
      - text: Show the transaction history for contact {contactId} on balance {balanceDefinitionId} in program {pid}.
        slots:
          contactId: query.contactId
          balanceDefinitionId: query.balanceDefinitionId
          pid: path.pid
      - text: List {status} transactions for contact {contactId} on balance {balanceDefinitionId} in program {pid}.
        slots:
          status: query.status
          contactId: query.contactId
          balanceDefinitionId: query.balanceDefinitionId
          pid: path.pid
      method: generated
      generated: '2026-09-26'