# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Merchant Custom Attributes API
  version: 1.0.0
extends: openapi/square-merchantcustomattributes-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/merchants/custom-attribute-definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List merchant custom attribute definitions
      effect: read
      questions:
      - What custom fields have been defined for my seller account?
      - Can I list only merchant attribute definitions that are read-write visible?
      instructions:
      - text: List merchant custom attribute definitions.
      - text: List merchant attribute definitions with visibility {visibility_filter}.
        slots:
          visibility_filter: query.visibility_filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/custom-attribute-definitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Define a new merchant custom attribute
      effect: write
      questions:
      - How do I define a new custom field that can be stored on the merchant?
      - Can I control who can see a new merchant-level custom attribute?
      instructions:
      - text: Create merchant custom attribute definition {custom_attribute_definition}.
        slots:
          custom_attribute_definition: requestBody.custom_attribute_definition
      - text: Define a new merchant-level attribute using {custom_attribute_definition}.
        slots:
          custom_attribute_definition: requestBody.custom_attribute_definition
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/custom-attribute-definitions/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a merchant custom attribute definition
      effect: read
      questions:
      - What schema and visibility does a merchant custom attribute definition have?
      - Can I fetch a specific version of a merchant attribute definition?
      instructions:
      - text: Get merchant custom attribute definition {key}.
        slots:
          key: path.key
      - text: Show merchant attribute definition {key} at version {version}.
        slots:
          key: path.key
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/custom-attribute-definitions/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a merchant custom attribute definition
      effect: write
      questions:
      - Can I rename or change the visibility of a merchant attribute definition?
      - Which fields on a merchant custom attribute definition are editable?
      instructions:
      - text: Update merchant custom attribute definition {key} with {custom_attribute_definition}.
        slots:
          key: path.key
          custom_attribute_definition: requestBody.custom_attribute_definition
      - text: Change the description of merchant 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/merchants/custom-attribute-definitions/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a merchant custom attribute definition
      effect: destructive
      questions:
      - Does deleting a merchant attribute definition also remove its stored values?
      - How do I retire a merchant-level custom field entirely?
      instructions:
      - text: Delete merchant custom attribute definition {key}.
        slots:
          key: path.key
      - text: Remove merchant attribute definition {key} and all its values.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/custom-attributes/bulk-delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete many merchant custom attributes
      effect: destructive
      questions:
      - Can I clear several merchant custom attribute values in one call?
      - What visibility is needed to delete a merchant attribute another app owns?
      instructions:
      - text: Bulk delete merchant custom attributes {values}.
        slots:
          values: requestBody.values
      - text: Clear all the merchant attribute values listed in {values}.
        slots:
          values: requestBody.values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/custom-attributes/bulk-upsert'].post
  update:
    x-apievangelist-phrasing:
      intent: Set many merchant custom attributes
      effect: write
      questions:
      - Can I set several custom attribute values on merchants at once?
      - Is there a bulk way to write merchant-level custom fields?
      instructions:
      - text: Bulk upsert merchant custom attributes {values}.
        slots:
          values: requestBody.values
      - text: Write all the merchant attribute values in {values} in one request.
        slots:
          values: requestBody.values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/{merchant_id}/custom-attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a merchant's custom attributes
      effect: read
      questions:
      - What custom attribute values are stored on a merchant?
      - Can I get the definitions along with a merchant's attribute values?
      instructions:
      - text: List custom attributes for merchant {merchant_id}.
        slots:
          merchant_id: path.merchant_id
      - text: List merchant {merchant_id}'s custom attributes with definitions {with_definitions}.
        slots:
          merchant_id: path.merchant_id
          with_definitions: query.with_definitions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/{merchant_id}/custom-attributes/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one merchant custom attribute
      effect: read
      questions:
      - What value does a specific custom attribute hold for a merchant?
      - Can I read one merchant attribute together with its definition?
      instructions:
      - text: Get custom attribute {key} for merchant {merchant_id}.
        slots:
          key: path.key
          merchant_id: path.merchant_id
      - text: Read merchant {merchant_id}'s value for attribute {key}.
        slots:
          merchant_id: path.merchant_id
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/{merchant_id}/custom-attributes/{key}'].post
  update:
    x-apievangelist-phrasing:
      intent: Set one merchant custom attribute
      effect: write
      questions:
      - How do I set a single custom attribute value on a merchant?
      - Does writing a merchant attribute overwrite an existing value?
      instructions:
      - text: Set attribute {key} on merchant {merchant_id} to {custom_attribute}.
        slots:
          key: path.key
          merchant_id: path.merchant_id
          custom_attribute: requestBody.custom_attribute
      - text: Upsert merchant {merchant_id}'s custom attribute {key} with {custom_attribute}.
        slots:
          merchant_id: path.merchant_id
          key: path.key
          custom_attribute: requestBody.custom_attribute
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/merchants/{merchant_id}/custom-attributes/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one merchant custom attribute
      effect: destructive
      questions:
      - Can I remove a single custom attribute value from a merchant?
      - Why would deleting a merchant attribute owned by another app fail?
      instructions:
      - text: Delete custom attribute {key} from merchant {merchant_id}.
        slots:
          key: path.key
          merchant_id: path.merchant_id
      - text: Clear merchant {merchant_id}'s value for attribute {key}.
        slots:
          merchant_id: path.merchant_id
          key: path.key
      method: generated
      generated: '2026-09-26'