# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Location Custom Attributes API
  version: 1.0.0
extends: openapi/square-locationcustomattributes-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: 11
- target: $.paths['/v2/locations/custom-attribute-definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List location custom field definitions
      effect: read
      questions:
      - What custom fields exist for my store locations?
      - Can I filter location custom attribute definitions by visibility?
      instructions:
      - text: List all location custom attribute definitions.
      - text: Show location custom field definitions with visibility {visibility_filter}.
        slots:
          visibility_filter: query.visibility_filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/custom-attribute-definitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Define a new custom field for locations
      effect: write
      questions:
      - How do I add a custom field, like a store manager, to my locations?
      - Can I define my own attribute that applies to every location?
      instructions:
      - text: Create location custom attribute definition {custom_attribute_definition}.
        slots:
          custom_attribute_definition: requestBody.custom_attribute_definition
      - text: 'Define a new custom field for my locations: {custom_attribute_definition}.'
        slots:
          custom_attribute_definition: requestBody.custom_attribute_definition
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/custom-attribute-definitions/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a location custom field definition
      effect: read
      questions:
      - What does one location custom attribute definition look like?
      - Can I read a specific version of a location custom field definition?
      instructions:
      - text: Get the location custom attribute definition {key}.
        slots:
          key: path.key
      - text: Show version {version} of location custom field definition {key}.
        slots:
          version: query.version
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/custom-attribute-definitions/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a location custom field definition
      effect: write
      questions:
      - How do I rename a custom field defined for locations?
      - Can I change the visibility or description of a location custom attribute definition?
      instructions:
      - text: Update location custom attribute definition {key} with {custom_attribute_definition}.
        slots:
          key: path.key
          custom_attribute_definition: requestBody.custom_attribute_definition
      - text: Change the definition of location custom field {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/custom-attribute-definitions/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a location custom field definition
      effect: destructive
      questions:
      - How do I remove a custom field definition from all my locations?
      - Does deleting a location custom attribute definition also delete its values?
      instructions:
      - text: Delete location custom attribute definition {key}.
        slots:
          key: path.key
      - text: Remove the location custom field {key} from my account.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/custom-attributes/bulk-delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete custom field values on many locations
      effect: destructive
      questions:
      - Can I clear custom field values from several locations at once?
      - Is there a bulk delete for location custom attributes?
      instructions:
      - text: 'Bulk delete these location custom attributes: {values}.'
        slots:
          values: requestBody.values
      - text: 'Remove custom field values from multiple locations: {values}.'
        slots:
          values: requestBody.values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/custom-attributes/bulk-upsert'].post
  update:
    x-apievangelist-phrasing:
      intent: Set custom field values on many locations
      effect: write
      questions:
      - How do I set a custom field value on all my stores in one call?
      - Can I bulk create or update location custom attributes?
      instructions:
      - text: Bulk upsert location custom attributes {values}.
        slots:
          values: requestBody.values
      - text: 'Set these custom field values across several locations: {values}.'
        slots:
          values: requestBody.values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/{location_id}/custom-attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a location's custom field values
      effect: read
      questions:
      - What custom field values are stored on one store location?
      - Can I get a location's custom attributes along with their definitions?
      instructions:
      - text: List custom attributes on location {location_id}.
        slots:
          location_id: path.location_id
      - text: 'Show custom field values for location {location_id} with definitions: {with_definitions}.'
        slots:
          location_id: path.location_id
          with_definitions: query.with_definitions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/{location_id}/custom-attributes/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one custom field value on a location
      effect: read
      questions:
      - How do I read a single custom field value for one location?
      - Can I fetch one location custom attribute with its definition included?
      instructions:
      - text: Get custom attribute {key} on location {location_id}.
        slots:
          key: path.key
          location_id: path.location_id
      - text: Read the {key} field value of store {location_id}.
        slots:
          key: path.key
          location_id: path.location_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/{location_id}/custom-attributes/{key}'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a custom field value on a location
      effect: write
      questions:
      - How do I save a custom field value on one store location?
      - Can I update an existing custom attribute on a single location?
      instructions:
      - text: Set custom attribute {key} on location {location_id} to {custom_attribute}.
        slots:
          key: path.key
          location_id: path.location_id
          custom_attribute: requestBody.custom_attribute
      - text: Upsert the {key} field on store {location_id}.
        slots:
          key: path.key
          location_id: path.location_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/locations/{location_id}/custom-attributes/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom field value from a location
      effect: destructive
      questions:
      - How do I clear one custom field value from a single location?
      - Can I remove a location's custom attribute without deleting its definition?
      instructions:
      - text: Delete custom attribute {key} from location {location_id}.
        slots:
          key: path.key
          location_id: path.location_id
      - text: Clear the {key} field on store {location_id}.
        slots:
          key: path.key
          location_id: path.location_id
      method: generated
      generated: '2026-09-26'