# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Inventory API
  version: 1.0.0
extends: openapi/square-inventory-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: 13
- target: $.paths['/v2/inventory/adjustment/{adjustment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an adjustment (deprecated URL)
      effect: read
      questions:
      - Is there an older singular adjustment URL for reading an inventory adjustment?
      - What does the deprecated inventory adjustment lookup return?
      instructions:
      - text: Get inventory adjustment {adjustment_id} using the deprecated singular endpoint.
        slots:
          adjustment_id: path.adjustment_id
      - text: Fetch adjustment {adjustment_id} through the legacy /inventory/adjustment path.
        slots:
          adjustment_id: path.adjustment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/adjustments/{adjustment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an inventory adjustment
      effect: read
      questions:
      - How do I view one inventory adjustment, like a sale or waste record?
      - Can I see what an inventory adjustment changed and when?
      instructions:
      - text: Get inventory adjustment {adjustment_id}.
        slots:
          adjustment_id: path.adjustment_id
      - text: Show me stock adjustment {adjustment_id} from the current adjustments endpoint.
        slots:
          adjustment_id: path.adjustment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/batch-change'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply stock changes (deprecated URL)
      effect: write
      questions:
      - Is the old batch-change inventory URL still usable?
      - What does the deprecated batch-change endpoint do?
      instructions:
      - text: Apply inventory changes {changes} through the deprecated batch-change endpoint.
        slots:
          changes: requestBody.changes
      - text: Use the legacy batch-change path to record {changes} with key {idempotency_key}.
        slots:
          changes: requestBody.changes
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/batch-retrieve-changes'].post
  update:
    x-apievangelist-phrasing:
      intent: Read stock history (deprecated URL)
      effect: read
      questions:
      - Is there a legacy batch-retrieve-changes URL for inventory history?
      - Does the deprecated changes lookup take the same filters as the new one?
      instructions:
      - text: Get inventory changes for {catalog_object_ids} via the deprecated batch-retrieve-changes endpoint.
        slots:
          catalog_object_ids: requestBody.catalog_object_ids
      - text: Use the legacy endpoint to list stock history at locations {location_ids}.
        slots:
          location_ids: requestBody.location_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/batch-retrieve-counts'].post
  update:
    x-apievangelist-phrasing:
      intent: Read stock counts (deprecated URL)
      effect: read
      questions:
      - Is the old batch-retrieve-counts URL still around for stock levels?
      - What does the deprecated inventory counts lookup return?
      instructions:
      - text: Get stock counts for {catalog_object_ids} via the deprecated batch-retrieve-counts endpoint.
        slots:
          catalog_object_ids: requestBody.catalog_object_ids
      - text: Use the legacy counts path to check stock at {location_ids}.
        slots:
          location_ids: requestBody.location_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/changes/batch-create'].post
  update:
    x-apievangelist-phrasing:
      intent: Adjust or recount stock in bulk
      effect: write
      questions:
      - How do I record a stock recount or adjustment for many items at once?
      - Can I skip counts that haven't changed when updating inventory?
      instructions:
      - text: Apply inventory changes {changes}.
        slots:
          changes: requestBody.changes
      - text: 'Record these stock adjustments and counts: {changes}, ignoring unchanged counts: {ignore_unchanged_counts}.'
        slots:
          changes: requestBody.changes
          ignore_unchanged_counts: requestBody.ignore_unchanged_counts
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/changes/batch-retrieve'].post
  update:
    x-apievangelist-phrasing:
      intent: Search inventory change history
      effect: read
      questions:
      - Where can I see the history of stock adjustments for my items?
      - Can I filter inventory history by date, location or change type?
      instructions:
      - text: List inventory changes for items {catalog_object_ids} at {location_ids}.
        slots:
          catalog_object_ids: requestBody.catalog_object_ids
          location_ids: requestBody.location_ids
      - text: Show stock history updated after {updated_after} of types {types}.
        slots:
          updated_after: requestBody.updated_after
          types: requestBody.types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/counts/batch-retrieve'].post
  update:
    x-apievangelist-phrasing:
      intent: Get current stock counts in bulk
      effect: read
      questions:
      - How much stock do I have of several items across my locations?
      - Can I fetch counts only for items that changed recently?
      instructions:
      - text: Get current stock counts for {catalog_object_ids} at {location_ids}.
        slots:
          catalog_object_ids: requestBody.catalog_object_ids
          location_ids: requestBody.location_ids
      - text: Show inventory counts changed since {updated_after}.
        slots:
          updated_after: requestBody.updated_after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/physical-count/{physical_count_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a physical count (deprecated URL)
      effect: read
      questions:
      - Is there an older singular physical-count URL for reading a stock count?
      - What does the deprecated physical count lookup return?
      instructions:
      - text: Get physical count {physical_count_id} using the deprecated singular endpoint.
        slots:
          physical_count_id: path.physical_count_id
      - text: Fetch count {physical_count_id} through the legacy /inventory/physical-count path.
        slots:
          physical_count_id: path.physical_count_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/physical-counts/{physical_count_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a physical stock count
      effect: read
      questions:
      - How do I view the record of a manual stock count?
      - Can I see who counted an item and what quantity they recorded?
      instructions:
      - text: Get physical count {physical_count_id}.
        slots:
          physical_count_id: path.physical_count_id
      - text: Show recount record {physical_count_id} from the current physical-counts endpoint.
        slots:
          physical_count_id: path.physical_count_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/transfers/{transfer_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an inventory transfer
      effect: read
      questions:
      - How can I view a stock transfer between two locations?
      - What quantity moved in a particular inventory transfer?
      instructions:
      - text: Get inventory transfer {transfer_id}.
        slots:
          transfer_id: path.transfer_id
      - text: Show the details of stock transfer {transfer_id}.
        slots:
          transfer_id: path.transfer_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/{catalog_object_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stock count for one item
      effect: read
      questions:
      - How many units of this one item do I have in stock?
      - Can I check a single item's stock at specific locations?
      instructions:
      - text: Get the current stock count of {catalog_object_id}.
        slots:
          catalog_object_id: path.catalog_object_id
      - text: Check stock of item {catalog_object_id} at locations {location_ids}.
        slots:
          catalog_object_id: path.catalog_object_id
          location_ids: query.location_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/inventory/{catalog_object_id}/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stock history for one item
      effect: read
      questions:
      - What adjustments and recounts has a single item had?
      - Can I see one product's inventory history at a location?
      instructions:
      - text: List inventory changes for item {catalog_object_id}.
        slots:
          catalog_object_id: path.catalog_object_id
      - text: Show stock history of {catalog_object_id} at {location_ids}.
        slots:
          catalog_object_id: path.catalog_object_id
          location_ids: query.location_ids
      method: generated
      generated: '2026-09-26'