# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Customers API
  version: 1.0.0
extends: openapi/square-customers-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: 14
- target: $.paths['/v2/customers'].get
  update:
    x-apievangelist-phrasing:
      intent: List customer profiles
      effect: read
      questions:
      - How do I page through every customer profile in my Square account?
      - Can I sort my customer list by creation date or name?
      - Can I get a total count of customers along with the list?
      instructions:
      - text: List all customers.
      - text: List customers sorted by {sort_field} in {sort_order} order.
        slots:
          sort_field: query.sort_field
          sort_order: query.sort_order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a customer profile
      effect: write
      questions:
      - What is the minimum info needed to add a new customer?
      - Can I store a birthday and note on a new customer profile?
      instructions:
      - text: Create a customer named {given_name} {family_name}.
        slots:
          given_name: requestBody.given_name
          family_name: requestBody.family_name
      - text: Add a new customer with email {email_address} and phone {phone_number}.
        slots:
          email_address: requestBody.email_address
          phone_number: requestBody.phone_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/bulk-create'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many customer profiles at once
      effect: write
      questions:
      - Can I import a batch of new customers in one request?
      - How do I bulk add customers from a spreadsheet?
      instructions:
      - text: 'Bulk create these customers: {customers}.'
        slots:
          customers: requestBody.customers
      - text: Import the new customer profiles in {customers} in one call.
        slots:
          customers: requestBody.customers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/bulk-delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete many customer profiles at once
      effect: destructive
      questions:
      - Can I delete a list of customers in a single call?
      - How do I remove several duplicate customer profiles together?
      instructions:
      - text: Bulk delete customers {customer_ids}.
        slots:
          customer_ids: requestBody.customer_ids
      - text: 'Remove all of these customer profiles: {customer_ids}.'
        slots:
          customer_ids: requestBody.customer_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/bulk-retrieve'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch several customers by ID
      effect: read
      questions:
      - Can I look up multiple customers at once when I already have their IDs?
      - What comes back if one of the customer IDs in a batch lookup is invalid?
      instructions:
      - text: Retrieve customers {customer_ids} in one call.
        slots:
          customer_ids: requestBody.customer_ids
      - text: Fetch the profiles for customer IDs {customer_ids}.
        slots:
          customer_ids: requestBody.customer_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/bulk-update'].post
  update:
    x-apievangelist-phrasing:
      intent: Update many customer profiles at once
      effect: write
      questions:
      - Is there a way to update many customer records in one request?
      - Can I change emails for a batch of existing customers together?
      instructions:
      - text: Bulk update customers with {customers}.
        slots:
          customers: requestBody.customers
      - text: Apply the profile changes in {customers} to those existing customers.
        slots:
          customers: requestBody.customers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search customers by filters
      effect: read
      questions:
      - How do I find customers by email, phone or creation date?
      - Can I search for customers who belong to a particular group?
      instructions:
      - text: Search customers matching {query}.
        slots:
          query: requestBody.query
      - text: Find customers that match the filters in {query}, up to {limit}.
        slots:
          query: requestBody.query
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one customer profile
      effect: read
      questions:
      - What contact details do we have for a specific customer?
      - Can I pull up a single customer profile by ID?
      instructions:
      - text: Get customer {customer_id}.
        slots:
          customer_id: path.customer_id
      - text: Show the profile for customer {customer_id}.
        slots:
          customer_id: path.customer_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one customer profile
      effect: write
      questions:
      - How do I change one customer's email address or phone number?
      - Can I remove a field from a customer profile with a sparse update?
      instructions:
      - text: Update customer {customer_id} email to {email_address}.
        slots:
          customer_id: path.customer_id
          email_address: requestBody.email_address
      - text: Change the phone number of customer {customer_id} to {phone_number}.
        slots:
          customer_id: path.customer_id
          phone_number: requestBody.phone_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one customer profile
      effect: destructive
      questions:
      - Can I delete a single customer profile permanently?
      - Which ID do I use to delete a customer created by merging profiles?
      instructions:
      - text: Delete customer {customer_id}.
        slots:
          customer_id: path.customer_id
      - text: Remove customer profile {customer_id} at version {version}.
        slots:
          customer_id: path.customer_id
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}/cards'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a card on a customer profile
      effect: write
      questions:
      - How do I save a card on file directly to a customer's profile from a card nonce?
      - Is adding a card nonce to a customer idempotent?
      instructions:
      - text: Add card {card_nonce} on file for customer {customer_id}.
        slots:
          card_nonce: requestBody.card_nonce
          customer_id: path.customer_id
      - text: Save card {card_nonce} to customer {customer_id} with cardholder name {cardholder_name}.
        slots:
          card_nonce: requestBody.card_nonce
          customer_id: path.customer_id
          cardholder_name: requestBody.cardholder_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}/cards/{card_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a card from a customer profile
      effect: destructive
      questions:
      - How do I remove a saved card from a customer's profile?
      - Can I delete one card on file without deleting the customer?
      instructions:
      - text: Delete card {card_id} from customer {customer_id}.
        slots:
          card_id: path.card_id
          customer_id: path.customer_id
      - text: Remove saved card {card_id} on customer {customer_id}'s profile.
        slots:
          card_id: path.card_id
          customer_id: path.customer_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}/groups/{group_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a customer to a group
      effect: write
      questions:
      - Can I put a customer into an existing customer group?
      - How do I tag a customer as a member of a group like VIPs?
      instructions:
      - text: Add customer {customer_id} to group {group_id}.
        slots:
          customer_id: path.customer_id
          group_id: path.group_id
      - text: Make customer {customer_id} a member of customer group {group_id}.
        slots:
          customer_id: path.customer_id
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}/groups/{group_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a customer from a group
      effect: destructive
      questions:
      - How do I take a customer out of a customer group?
      - Can I drop one customer's group membership without deleting the group?
      instructions:
      - text: Remove customer {customer_id} from group {group_id}.
        slots:
          customer_id: path.customer_id
          group_id: path.group_id
      - text: End customer {customer_id}'s membership in group {group_id}.
        slots:
          customer_id: path.customer_id
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'