API Evangelist conversational phrasing for Overview Products API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Overview Products API
  version: 1.0.0
extends: openapi/aftership-products-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: 8
- target: $.paths['/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search products in a store
      effect: read
      questions:
      - How do I list the products in my store?
      - Can I search products by keyword or show only published ones?
      instructions:
      - text: List products in store {store}.
        slots:
          store: header.as-store-id
      - text: Search products for {search}.
        slots:
          search: query.search
      - text: Get the products with slugs {slugs}.
        slots:
          slugs: query.slugs[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/products'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a product with variants
      effect: write
      questions:
      - How do I add a new product to my store catalog?
      - What's required to create a product, like images and variants?
      instructions:
      - text: Create product {title} with images {image_urls} and variants {variants}.
        slots:
          title: requestBody.title
          image_urls: requestBody.image_urls
          variants: requestBody.variants
      - text: Add a product to store {store} with variants {variants}.
        slots:
          store: header.as-store-id
          variants: requestBody.variants
      method: generated
      generated: '2026-09-26'
- target: $.paths['/products/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product by ID
      effect: read
      questions:
      - What are the details of a specific product?
      - Can I look up one product and its variants by ID?
      instructions:
      - text: Show product {id}.
        slots:
          id: path.id
      - text: Get product {id} from store {store}.
        slots:
          id: path.id
          store: header.as-store-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/products/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a product's details
      effect: write
      questions:
      - Can I change a product's title or description?
      - How do I unpublish a product?
      instructions:
      - text: Rename product {id} to {title}.
        slots:
          id: path.id
          title: requestBody.title
      - text: Set product {id} published to {published}.
        slots:
          id: path.id
          published: requestBody.published
      method: generated
      generated: '2026-09-26'
- target: $.paths['/products/{id}/variants'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a variant to a product
      effect: write
      questions:
      - How do I add a new size or color variant to a product?
      - Can a new variant allow backorders?
      instructions:
      - text: Add variant {variant_id} with SKU {sku} priced {price}.
        slots:
          variant_id: requestBody.id
          sku: requestBody.sku
          price: requestBody.price
      - text: Create a new product variant {title} with {available_quantity} in stock.
        slots:
          title: requestBody.title
          available_quantity: requestBody.available_quantity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/products/{id}/variants/{variant_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product variant
      effect: read
      questions:
      - What are the details of one variant of a product?
      - Can I retrieve a single product variant by its ID?
      instructions:
      - text: Get a specific product variant from store {store}.
        slots:
          store: header.as-store-id
      - text: Show the price and stock of one product variant.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/products/{id}/variants/{variant_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a product variant
      effect: destructive
      questions:
      - How do I remove a variant I no longer sell?
      - Can I delete one variant without deleting the product?
      instructions:
      - text: Delete a product variant in store {store}.
        slots:
          store: header.as-store-id
      - text: Remove a discontinued variant from its product.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/products/{id}/variants/{variant_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a product variant
      effect: write
      questions:
      - How do I change a variant's price or stock level?
      - Can I update a variant's compare-at price?
      instructions:
      - text: Set the variant price to {price}.
        slots:
          price: requestBody.price
      - text: Update the variant's available quantity to {available_quantity}.
        slots:
          available_quantity: requestBody.available_quantity
      method: generated
      generated: '2026-09-26'