API Evangelist conversational phrasing for Square Catalog API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Catalog API
  version: 1.0.0
extends: openapi/square-catalog-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/catalog/batch-delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete several catalog objects at once
      effect: destructive
      questions:
      - How do I delete a bunch of catalog items in one request?
      - Does deleting items in bulk also remove their variations?
      instructions:
      - text: Delete catalog objects {object_ids}.
        slots:
          object_ids: requestBody.object_ids
      - text: 'Bulk-remove these items from my catalog: {object_ids}.'
        slots:
          object_ids: requestBody.object_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/batch-retrieve'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch several catalog objects by ID
      effect: read
      questions:
      - Can I fetch many catalog items by their IDs in one call?
      - Is it possible to include related objects like taxes when fetching items by ID?
      instructions:
      - text: Get catalog objects {object_ids}.
        slots:
          object_ids: requestBody.object_ids
      - text: 'Retrieve items {object_ids} with related objects included: {include_related_objects}.'
        slots:
          object_ids: requestBody.object_ids
          include_related_objects: requestBody.include_related_objects
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/batch-upsert'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update catalog objects in bulk
      effect: write
      questions:
      - How do I import thousands of products into my Square catalog at once?
      - What happens if one object in a batch upsert fails?
      instructions:
      - text: 'Upsert these catalog batches: {batches}.'
        slots:
          batches: requestBody.batches
      - text: Bulk create or update catalog objects from {batches} with key {idempotency_key}.
        slots:
          batches: requestBody.batches
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/images'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a catalog image
      effect: write
      questions:
      - How do I add a product photo to an item in my catalog?
      - Can I upload an image and attach it to an existing catalog object?
      instructions:
      - text: Upload {image_file} as a new catalog image.
        slots:
          image_file: requestBody.image_file
      - text: Create a catalog image from {image_file} using {request}.
        slots:
          image_file: requestBody.image_file
          request: requestBody.request
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/images/{image_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an existing catalog image file
      effect: write
      questions:
      - Can I swap out the photo on an existing catalog image?
      - How do I replace the file behind a catalog image without creating a new one?
      instructions:
      - text: Replace the file of catalog image {image_id} with {image_file}.
        slots:
          image_id: path.image_id
          image_file: requestBody.image_file
      - text: Update catalog image {image_id} with a new upload.
        slots:
          image_id: path.image_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/info'].get
  update:
    x-apievangelist-phrasing:
      intent: Get catalog API batch size limits
      effect: read
      questions:
      - What are the batch size limits for catalog upserts?
      - Where do I find the Catalog API's limits and settings?
      instructions:
      - text: Show me the Catalog API limits.
      - text: Check the maximum batch sizes for catalog requests.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalog objects by type
      effect: read
      questions:
      - How do I list all items and categories in my catalog?
      - Can I list only certain object types, like taxes or discounts?
      instructions:
      - text: List all catalog objects of types {types}.
        slots:
          types: query.types
      - text: Page through my full catalog.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/object'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update one catalog object
      effect: write
      questions:
      - How do I add a single new item to my Square catalog?
      - Can I update one existing catalog object without a batch?
      instructions:
      - text: Create or update catalog object {object}.
        slots:
          object: requestBody.object
      - text: 'Save this single item to my catalog: {object}.'
        slots:
          object: requestBody.object
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/object/{object_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one catalog object
      effect: read
      questions:
      - How can I view one catalog item with all its variations?
      - Can I see a catalog object as it was at a past catalog version?
      instructions:
      - text: Get catalog object {object_id}.
        slots:
          object_id: path.object_id
      - text: Show item {object_id} as of catalog version {catalog_version}.
        slots:
          object_id: path.object_id
          catalog_version: query.catalog_version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/object/{object_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one catalog object
      effect: destructive
      questions:
      - How do I remove a single item from my catalog?
      - Will deleting one catalog item also delete its child variations?
      instructions:
      - text: Delete catalog object {object_id}.
        slots:
          object_id: path.object_id
      - text: Remove item {object_id} from my catalog.
        slots:
          object_id: path.object_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search catalog objects of any type
      effect: read
      questions:
      - Can I search catalog objects of any type by attribute values?
      - Is there a way to find catalog objects changed since a certain time?
      instructions:
      - text: Search catalog objects of types {object_types} matching {query}.
        slots:
          object_types: requestBody.object_types
          query: requestBody.query
      - text: Find catalog objects updated since {begin_time}.
        slots:
          begin_time: requestBody.begin_time
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/search-catalog-items'].post
  update:
    x-apievangelist-phrasing:
      intent: Search items by text, category or stock
      effect: read
      questions:
      - How do I search my products by name or category?
      - Can I find items that are low on stock or enabled at a location?
      - Does item search support filtering on custom attribute values?
      instructions:
      - text: Search catalog items for {text_filter}.
        slots:
          text_filter: requestBody.text_filter
      - text: Find items in categories {category_ids} with stock levels {stock_levels}.
        slots:
          category_ids: requestBody.category_ids
          stock_levels: requestBody.stock_levels
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/update-item-modifier-lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Enable or disable modifier lists on items
      effect: write
      questions:
      - How do I attach a modifier list, like toppings, to several items?
      - Can I turn off a modifier list on items without re-saving the whole item?
      instructions:
      - text: Enable modifier lists {modifier_lists_to_enable} on items {item_ids}.
        slots:
          modifier_lists_to_enable: requestBody.modifier_lists_to_enable
          item_ids: requestBody.item_ids
      - text: Disable modifier lists {modifier_lists_to_disable} for items {item_ids}.
        slots:
          modifier_lists_to_disable: requestBody.modifier_lists_to_disable
          item_ids: requestBody.item_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/catalog/update-item-taxes'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply or remove taxes on items
      effect: write
      questions:
      - How do I apply a sales tax to a group of catalog items?
      - Can I remove a tax from items without upserting the entire item?
      instructions:
      - text: Apply taxes {taxes_to_enable} to items {item_ids}.
        slots:
          taxes_to_enable: requestBody.taxes_to_enable
          item_ids: requestBody.item_ids
      - text: Stop charging taxes {taxes_to_disable} on items {item_ids}.
        slots:
          taxes_to_disable: requestBody.taxes_to_disable
          item_ids: requestBody.item_ids
      method: generated
      generated: '2026-09-26'