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