# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Customer Custom Attributes API
  version: 1.0.0
extends: openapi/square-customercustomattributes-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: 10
- target: $.paths['/v2/customers/custom-attribute-definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List customer custom attribute definitions
      effect: read
      questions:
      - What custom fields have been defined for customer profiles?
      - Can I page through all customer attribute definitions in my account?
      instructions:
      - text: List customer custom attribute definitions.
      - text: Show customer attribute definitions, {limit} per page.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/custom-attribute-definitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Define a new customer custom attribute
      effect: write
      questions:
      - How do I add a custom field like favorite drink to customer profiles?
      - Can I set the data type and visibility of a new customer attribute?
      instructions:
      - text: Create customer custom attribute definition {custom_attribute_definition}.
        slots:
          custom_attribute_definition: requestBody.custom_attribute_definition
      - text: Define a new customer profile field using {custom_attribute_definition}.
        slots:
          custom_attribute_definition: requestBody.custom_attribute_definition
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/custom-attribute-definitions/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer custom attribute definition
      effect: read
      questions:
      - What schema does a customer custom attribute definition use?
      - Can I read a specific version of a customer attribute definition?
      instructions:
      - text: Get customer custom attribute definition {key}.
        slots:
          key: path.key
      - text: Show customer attribute definition {key} at version {version}.
        slots:
          key: path.key
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/custom-attribute-definitions/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a customer custom attribute definition
      effect: write
      questions:
      - Can I change the name or visibility of a customer attribute definition?
      - Which parts of a customer custom attribute definition are editable?
      instructions:
      - text: Update customer custom attribute definition {key} with {custom_attribute_definition}.
        slots:
          key: path.key
          custom_attribute_definition: requestBody.custom_attribute_definition
      - text: Rename customer attribute definition {key} per {custom_attribute_definition}.
        slots:
          key: path.key
          custom_attribute_definition: requestBody.custom_attribute_definition
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/custom-attribute-definitions/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a customer custom attribute definition
      effect: destructive
      questions:
      - Will deleting a customer attribute definition wipe its values from all profiles?
      - How do I retire a custom field from customer profiles?
      instructions:
      - text: Delete customer custom attribute definition {key}.
        slots:
          key: path.key
      - text: Remove customer attribute definition {key} and its values on every profile.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/custom-attributes/bulk-upsert'].post
  update:
    x-apievangelist-phrasing:
      intent: Set custom attributes on many customers
      effect: write
      questions:
      - Can I set custom field values on many customer profiles in one request?
      - Is there a bulk way to fill a custom attribute across customers?
      instructions:
      - text: Bulk upsert customer custom attributes {values}.
        slots:
          values: requestBody.values
      - text: Write the customer attribute values in {values} across those profiles.
        slots:
          values: requestBody.values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}/custom-attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a customer's custom attributes
      effect: read
      questions:
      - Which custom attribute values are stored on a customer profile?
      - Can I get a customer's attributes with their definitions included?
      instructions:
      - text: List custom attributes for customer {customer_id}.
        slots:
          customer_id: path.customer_id
      - text: List customer {customer_id}'s custom attributes with definitions {with_definitions}.
        slots:
          customer_id: path.customer_id
          with_definitions: query.with_definitions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}/custom-attributes/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one customer custom attribute
      effect: read
      questions:
      - What value does a customer have for one particular custom field?
      - Can I read a single customer attribute along with its definition?
      instructions:
      - text: Get custom attribute {key} for customer {customer_id}.
        slots:
          key: path.key
          customer_id: path.customer_id
      - text: Read customer {customer_id}'s value for attribute {key}.
        slots:
          customer_id: path.customer_id
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}/custom-attributes/{key}'].post
  update:
    x-apievangelist-phrasing:
      intent: Set one custom attribute on a customer
      effect: write
      questions:
      - How do I set a custom field value on a single customer profile?
      - Does setting a customer attribute replace the previous value?
      instructions:
      - text: Set attribute {key} on customer {customer_id} to {custom_attribute}.
        slots:
          key: path.key
          customer_id: path.customer_id
          custom_attribute: requestBody.custom_attribute
      - text: Upsert customer {customer_id}'s custom attribute {key} with {custom_attribute}.
        slots:
          customer_id: path.customer_id
          key: path.key
          custom_attribute: requestBody.custom_attribute
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer_id}/custom-attributes/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one custom attribute from a customer
      effect: destructive
      questions:
      - Can I clear one custom field value from a customer profile?
      - Why might deleting a customer attribute owned by another app fail?
      instructions:
      - text: Delete custom attribute {key} from customer {customer_id}.
        slots:
          key: path.key
          customer_id: path.customer_id
      - text: Clear customer {customer_id}'s value for attribute {key}.
        slots:
          customer_id: path.customer_id
          key: path.key
      method: generated
      generated: '2026-09-26'