# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Loyalty API
  version: 1.0.0
extends: openapi/square-loyalty-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['/v2/loyalty/accounts'].post
  update:
    x-apievangelist-phrasing:
      intent: Enroll a buyer in the loyalty program
      effect: write
      questions:
      - How do I sign a customer up for my Square loyalty program using their phone number?
      - What do I need to open a new loyalty account for a buyer?
      instructions:
      - text: Create a loyalty account from {loyalty_account}.
        slots:
          loyalty_account: requestBody.loyalty_account
      - text: Enroll this buyer in my loyalty program using {loyalty_account}, with idempotency key {idempotency_key}.
        slots:
          loyalty_account: requestBody.loyalty_account
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/accounts/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Find loyalty accounts by phone or customer
      effect: read
      questions:
      - Can I look up a loyalty member by their phone number?
      - Which loyalty accounts are tied to a given customer ID?
      - Is there a way to page through every loyalty account in my program?
      instructions:
      - text: Search loyalty accounts matching {query}.
        slots:
          query: requestBody.query
      - text: Find up to {limit} loyalty accounts in my program.
        slots:
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/accounts/{account_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a loyalty account
      effect: read
      questions:
      - How can I see the point balance on one specific loyalty account?
      - What details come back for a single loyalty account by its ID?
      instructions:
      - text: Show me loyalty account {account_id}.
        slots:
          account_id: path.account_id
      - text: Pull up the balance and details of loyalty account {account_id}.
        slots:
          account_id: path.account_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/accounts/{account_id}/accumulate'].post
  update:
    x-apievangelist-phrasing:
      intent: Award points earned from a purchase
      effect: write
      questions:
      - How do I give a loyalty member the points they earned on an order?
      - Can points be credited from a purchase at a specific location?
      instructions:
      - text: Add the points earned from {accumulate_points} to loyalty account {account_id} at location {location_id}.
        slots:
          accumulate_points: requestBody.accumulate_points
          account_id: path.account_id
          location_id: requestBody.location_id
      - text: Credit purchase points to loyalty account {account_id} for the sale at {location_id}.
        slots:
          account_id: path.account_id
          location_id: requestBody.location_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/accounts/{account_id}/adjust'].post
  update:
    x-apievangelist-phrasing:
      intent: Manually add or subtract loyalty points
      effect: write
      questions:
      - How do I manually correct a buyer's loyalty point balance?
      - Can a manual points adjustment leave an account with a negative balance?
      instructions:
      - text: Adjust the points on loyalty account {account_id} by {adjust_points}.
        slots:
          account_id: path.account_id
          adjust_points: requestBody.adjust_points
      - text: 'Deduct points from loyalty account {account_id} with {adjust_points}, allowing a negative balance: {allow_negative_balance}.'
        slots:
          account_id: path.account_id
          adjust_points: requestBody.adjust_points
          allow_negative_balance: requestBody.allow_negative_balance
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/events/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search the loyalty points ledger
      effect: read
      questions:
      - Where can I see the history of points earned and redeemed on loyalty accounts?
      - Can I filter loyalty events by type or date range?
      instructions:
      - text: Search loyalty events matching {query}.
        slots:
          query: requestBody.query
      - text: Show the last {limit} loyalty ledger events.
        slots:
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/programs'].get
  update:
    x-apievangelist-phrasing:
      intent: List the seller's loyalty programs
      effect: read
      questions:
      - What loyalty program does my Square account have set up?
      - Is there a call that returns my loyalty programs without knowing the program ID?
      instructions:
      - text: List my loyalty programs.
      - text: Show every loyalty program on this seller account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/programs/{program_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a loyalty program's rules
      effect: read
      questions:
      - How do I read the earning rules and reward tiers of my loyalty program?
      - Can I fetch the loyalty program using the keyword main instead of an ID?
      instructions:
      - text: Get loyalty program {program_id} with its reward tiers.
        slots:
          program_id: path.program_id
      - text: Show the accrual rules for loyalty program {program_id}.
        slots:
          program_id: path.program_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/programs/{program_id}/calculate'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview points a purchase would earn
      effect: read
      questions:
      - How many loyalty points would a buyer earn on this purchase?
      - Can I estimate points from a transaction amount without an order?
      instructions:
      - text: Calculate the points order {order_id} would earn in program {program_id}.
        slots:
          order_id: requestBody.order_id
          program_id: path.program_id
      - text: Estimate loyalty points for a {transaction_amount_money} purchase in program {program_id}.
        slots:
          transaction_amount_money: requestBody.transaction_amount_money
          program_id: path.program_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/programs/{program_id}/promotions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a loyalty program's promotions
      effect: read
      questions:
      - Which bonus-point promotions are running on my loyalty program?
      - Can I list only scheduled or canceled loyalty promotions?
      instructions:
      - text: List promotions for loyalty program {program_id}.
        slots:
          program_id: path.program_id
      - text: Show {status} promotions in loyalty program {program_id}.
        slots:
          status: query.status
          program_id: path.program_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/programs/{program_id}/promotions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a bonus-points promotion
      effect: write
      questions:
      - How do I run a double-points promotion on my loyalty program?
      - Can buyers earn extra points on top of the base program for a limited time?
      instructions:
      - text: Create loyalty promotion {loyalty_promotion} on program {program_id}.
        slots:
          loyalty_promotion: requestBody.loyalty_promotion
          program_id: path.program_id
      - text: Set up a bonus-points promotion in program {program_id} using {loyalty_promotion}.
        slots:
          program_id: path.program_id
          loyalty_promotion: requestBody.loyalty_promotion
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/programs/{program_id}/promotions/{promotion_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a loyalty promotion
      effect: read
      questions:
      - What are the details and status of one loyalty promotion?
      - Can I check when a specific points promotion ends?
      instructions:
      - text: Get promotion {promotion_id} from loyalty program {program_id}.
        slots:
          promotion_id: path.promotion_id
          program_id: path.program_id
      - text: Show me the settings of loyalty promotion {promotion_id} in program {program_id}.
        slots:
          promotion_id: path.promotion_id
          program_id: path.program_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/programs/{program_id}/promotions/{promotion_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a loyalty promotion
      effect: destructive
      questions:
      - How do I end an active points promotion before its end date?
      - Can I cancel a loyalty promotion that is only scheduled?
      instructions:
      - text: Cancel loyalty promotion {promotion_id} in program {program_id}.
        slots:
          promotion_id: path.promotion_id
          program_id: path.program_id
      - text: Stop promotion {promotion_id} early on loyalty program {program_id}.
        slots:
          promotion_id: path.promotion_id
          program_id: path.program_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/rewards'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a loyalty reward and lock points
      effect: write
      questions:
      - How do I turn a buyer's points into a reward they can use?
      - Does creating a reward lock the points for the chosen reward tier?
      instructions:
      - text: Create loyalty reward {reward}.
        slots:
          reward: requestBody.reward
      - text: Lock points for a reward tier by creating reward {reward}.
        slots:
          reward: requestBody.reward
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/rewards/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search loyalty rewards
      effect: read
      questions:
      - Which rewards has a loyalty account issued or redeemed?
      - Can I filter loyalty rewards by status for one account?
      instructions:
      - text: Search loyalty rewards matching {query}.
        slots:
          query: requestBody.query
      - text: List up to {limit} loyalty rewards across all accounts.
        slots:
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/rewards/{reward_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a loyalty reward
      effect: read
      questions:
      - What state is a particular loyalty reward in?
      - Can I look up one reward by its ID to see its points?
      instructions:
      - text: Get loyalty reward {reward_id}.
        slots:
          reward_id: path.reward_id
      - text: Show me the details of reward {reward_id}.
        slots:
          reward_id: path.reward_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/rewards/{reward_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a reward and return its points
      effect: destructive
      questions:
      - How do I undo a loyalty reward and give the points back to the buyer?
      - Does deleting a reward remove its discount from the order?
      instructions:
      - text: Delete loyalty reward {reward_id}.
        slots:
          reward_id: path.reward_id
      - text: Remove reward {reward_id} and return its points to the account.
        slots:
          reward_id: path.reward_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty/rewards/{reward_id}/redeem'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeem a loyalty reward
      effect: write
      questions:
      - How do I mark a loyalty reward as redeemed after the buyer uses it?
      - Is redeeming a reward final once it is in the redeemed state?
      instructions:
      - text: Redeem loyalty reward {reward_id} at location {location_id}.
        slots:
          reward_id: path.reward_id
          location_id: requestBody.location_id
      - text: Mark reward {reward_id} as used at {location_id}.
        slots:
          reward_id: path.reward_id
          location_id: requestBody.location_id
      method: generated
      generated: '2026-09-26'