API Evangelist conversational phrasing for Squarespace 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 Squarespace Products API
  version: 1.0.0
extends: openapi/squarespace-products-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 25
- target: $.paths['/v2/commerce/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List and search products (v2)
      effect: read
      questions:
      - How do I list all products of one type with the v2 products API?
      - Can I search v2 products by keyword or by when they were last modified?
      instructions:
      - text: List v2 products of type {type}.
        slots:
          type: query.type
      - text: Search v2 products for {query}.
        slots:
          query: query.query
      - text: List v2 products modified between {modifiedAfter} and {modifiedBefore}.
        slots:
          modifiedAfter: query.modifiedAfter
          modifiedBefore: query.modifiedBefore
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a product (v2)
      effect: write
      questions:
      - How do I add a new product to my store with the v2 products API?
      - Does v2 product creation set up the right subresources for each product type?
      instructions:
      - text: Create a new product through the v2 products endpoint.
      - text: Create a v2 product, sending user agent {user_agent}.
        slots:
          user_agent: header.User-Agent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productIdCsvs}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get specific products by ID (v2)
      effect: read
      questions:
      - How do I fetch a handful of products, with variants and images, by ID on v2?
      - How many products can one v2 by-ID request return?
      instructions:
      - text: Get v2 products {productIdCsvs}.
        slots:
          productIdCsvs: path.productIdCsvs
      - text: Show variants and images for v2 products {productIdCsvs}.
        slots:
          productIdCsvs: path.productIdCsvs
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a product's details (v2)
      effect: write
      questions:
      - How do I hide a product from my storefront with the v2 API?
      - Can I change a product's URL slug or SEO data on v2 without resending everything?
      instructions:
      - text: Rename v2 product {productId} to {name}.
        slots:
          productId: path.productId
          name: requestBody.name
      - text: Set v2 product {productId} visibility to {isVisible}.
        slots:
          productId: path.productId
          isVisible: requestBody.isVisible
      - text: Update the SEO data of v2 product {productId} to {seoData}.
        slots:
          productId: path.productId
          seoData: requestBody.seoData
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a product (v2)
      effect: destructive
      questions:
      - How do I delete a product with the v2 products API?
      - Can I remove a discontinued product from the v2 catalog by its ID?
      instructions:
      - text: Delete v2 product {productId}.
        slots:
          productId: path.productId
      - text: Remove product {productId} from the catalog via v2.
        slots:
          productId: path.productId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/images'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a product image (v2)
      effect: write
      questions:
      - How do I upload a photo for a product with the v2 API?
      - Does uploading a v2 product image make it the featured image?
      instructions:
      - text: Upload an image to v2 product {productId}.
        slots:
          productId: path.productId
      - text: Add a new photo file to product {productId} using v2.
        slots:
          productId: path.productId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/images/{imageId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a product image's alt text (v2)
      effect: write
      questions:
      - How do I change the alt text on a product image with v2?
      - What can I edit on an existing v2 product image besides alt text?
      instructions:
      - text: Set the alt text of image {imageId} on v2 product {productId} to {altText}.
        slots:
          imageId: path.imageId
          productId: path.productId
          altText: requestBody.altText
      - text: Update v2 image {imageId} of product {productId} with alt text {altText}.
        slots:
          imageId: path.imageId
          productId: path.productId
          altText: requestBody.altText
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/images/{imageId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a product image (v2)
      effect: destructive
      questions:
      - How do I delete one image from a product with the v2 API?
      - Can I remove an outdated photo from a v2 product listing?
      instructions:
      - text: Delete image {imageId} from v2 product {productId}.
        slots:
          imageId: path.imageId
          productId: path.productId
      - text: Remove photo {imageId} on product {productId} using v2.
        slots:
          imageId: path.imageId
          productId: path.productId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/images/{imageId}/order'].post
  update:
    x-apievangelist-phrasing:
      intent: Move one product image after another (v2)
      effect: write
      questions:
      - How do I move a single product image to sit after another image on v2?
      - Can I change where one image appears on the product details page?
      instructions:
      - text: Move image {imageId} of v2 product {productId} to after image {afterImageId}.
        slots:
          imageId: path.imageId
          productId: path.productId
          afterImageId: requestBody.afterImageId
      - text: Reposition v2 image {imageId} on product {productId} behind {afterImageId}.
        slots:
          imageId: path.imageId
          productId: path.productId
          afterImageId: requestBody.afterImageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/images/{imageId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an uploaded image's processing status
      effect: read
      questions:
      - Is my uploaded product image still processing, ready, or in error?
      - How do I know when a newly uploaded product image is ready to use?
      instructions:
      - text: Check the processing status of image {imageId} on product {productId}.
        slots:
          imageId: path.imageId
          productId: path.productId
      - text: Tell me whether upload {imageId} for product {productId} finished processing.
        slots:
          imageId: path.imageId
          productId: path.productId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/variants'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a variant to a product (v2)
      effect: write
      questions:
      - How do I add a new size or color variant to a product with v2?
      - Can I set a GTIN or MPN when creating a v2 variant?
      - Why does creating a variant fail for a physical product with no attributes?
      instructions:
      - text: Add a v2 variant with SKU {sku} and pricing {pricing} to product {productId}.
        slots:
          sku: requestBody.sku
          pricing: requestBody.pricing
          productId: path.productId
      - text: Create v2 variant {sku} on product {productId} priced {pricing} with attributes {attributes} and GTIN {gtin}.
        slots:
          sku: requestBody.sku
          productId: path.productId
          pricing: requestBody.pricing
          attributes: requestBody.attributes
          gtin: requestBody.gtin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/variants/{variantId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a product variant (v2)
      effect: write
      questions:
      - How do I change the price of one variant with the v2 API?
      - Can I update a v2 variant's shipping measurements?
      instructions:
      - text: Set pricing of v2 variant {variantId} on product {productId} to {pricing}.
        slots:
          variantId: path.variantId
          productId: path.productId
          pricing: requestBody.pricing
      - text: Change the SKU of v2 variant {variantId} of product {productId} to {sku}.
        slots:
          variantId: path.variantId
          productId: path.productId
          sku: requestBody.sku
      - text: Update shipping measurements of v2 variant {variantId} on {productId} to {shippingMeasurements}.
        slots:
          variantId: path.variantId
          productId: path.productId
          shippingMeasurements: requestBody.shippingMeasurements
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/variants/{variantId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a product variant
      effect: destructive
      questions:
      - How do I remove a variant I no longer sell from a product?
      - Can I delete one variant without deleting the whole product?
      instructions:
      - text: Delete variant {variantId} from product {productId}.
        slots:
          variantId: path.variantId
          productId: path.productId
      - text: Remove the variant {variantId} of product {productId}.
        slots:
          variantId: path.variantId
          productId: path.productId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/commerce/products/{productId}/variants/{variantId}/image'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign an image to a variant
      effect: write
      questions:
      - How do I show a specific photo when a shopper picks a variant?
      - Can I clear the image linked to a variant?
      instructions:
      - text: Assign image {imageId} to variant {variantId} of product {productId}.
        slots:
          imageId: requestBody.imageId
          variantId: path.variantId
          productId: path.productId
      - text: Link variant {variantId} on product {productId} to photo {imageId}.
        slots:
          variantId: path.variantId
          productId: path.productId
          imageId: requestBody.imageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List products (unversioned)
      effect: read
      questions:
      - What products are in my catalog, via the unversioned products path?
      - Can the unversioned product listing be filtered by product type?
      instructions:
      - text: Retrieve unversioned products of type {type}.
        slots:
          type: query.type
      - text: Continue the unversioned product listing from cursor {cursor}.
        slots:
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a product with variants (unversioned)
      effect: write
      questions:
      - Can I create a gift card or digital download product via the unversioned path?
      - What must an unversioned product creation request include besides the name?
      instructions:
      - text: Create an unversioned {type} product named {name} with variants {variants}.
        slots:
          type: requestBody.type
          name: requestBody.name
          variants: requestBody.variants
      - text: Add product {name} of type {type} with variants {variants} and visibility {isVisible}.
        slots:
          name: requestBody.name
          type: requestBody.type
          variants: requestBody.variants
          isVisible: requestBody.isVisible
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productIds}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get specific products by ID (unversioned)
      effect: read
      questions:
      - How do I retrieve up to 50 products by ID without the v2 prefix?
      - Can I get full variant and image data for specific products via the unversioned path?
      instructions:
      - text: Retrieve unversioned products {productIds}.
        slots:
          productIds: path.productIds
      - text: Pull full product data for IDs {productIds} from the unversioned endpoint.
        slots:
          productIds: path.productIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productIds}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a product (unversioned)
      effect: write
      questions:
      - How do I change a product's tags via the unversioned path?
      - Can I update just the description of a product without the v2 prefix?
      instructions:
      - text: Set the tags on unversioned product {productIds} to {tags}.
        slots:
          productIds: path.productIds
          tags: requestBody.tags
      - text: Update the description of product {productIds} to {description} via the unversioned endpoint.
        slots:
          productIds: path.productIds
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productIds}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a product (unversioned)
      effect: destructive
      questions:
      - Does deleting a product through the unversioned path also remove its variants and images?
      - Can I undo a product deletion made without the v2 prefix?
      instructions:
      - text: Permanently delete unversioned product {productIds}.
        slots:
          productIds: path.productIds
      - text: Delete product {productIds} with all its variants and images using the unversioned endpoint.
        slots:
          productIds: path.productIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productId}/variants'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a variant (unversioned)
      effect: write
      questions:
      - How do I add a variant with its own stock tracking via the unversioned path?
      - Can I create a variant without the v2 prefix?
      instructions:
      - text: Add an unversioned variant {sku} priced {pricing} to product {productId}.
        slots:
          sku: requestBody.sku
          pricing: requestBody.pricing
          productId: path.productId
      - text: Create variant {sku} on product {productId} at {pricing} with stock settings {stock}, unversioned.
        slots:
          sku: requestBody.sku
          productId: path.productId
          pricing: requestBody.pricing
          stock: requestBody.stock
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productId}/variants/{variantId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a variant's price, SKU or stock (unversioned)
      effect: write
      questions:
      - How do I change a variant's stock tracking settings via the unversioned path?
      - Can I edit a variant's option values without the v2 prefix?
      instructions:
      - text: Update stock settings of unversioned variant {variantId} on product {productId} to {stock}.
        slots:
          variantId: path.variantId
          productId: path.productId
          stock: requestBody.stock
      - text: Change option values of variant {variantId} on product {productId} to {attributes}, unversioned.
        slots:
          variantId: path.variantId
          productId: path.productId
          attributes: requestBody.attributes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productId}/images'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a product image from a URL (unversioned)
      effect: write
      questions:
      - Can I add a product image by pointing at a public image URL?
      - How do I set alt text while uploading an image via the unversioned path?
      instructions:
      - text: Upload the image at {url} to product {productId}.
        slots:
          url: requestBody.url
          productId: path.productId
      - text: Add image {url} to product {productId} with alt text {altText}, unversioned.
        slots:
          url: requestBody.url
          productId: path.productId
          altText: requestBody.altText
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productId}/images/{imageId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Edit a product image's alt text (unversioned)
      effect: write
      questions:
      - How do I fix the accessibility alt text on a product image via the unversioned path?
      - Can I replace the actual image file of an existing product image?
      instructions:
      - text: Change unversioned image {imageId} on product {productId} to alt text {altText}.
        slots:
          imageId: path.imageId
          productId: path.productId
          altText: requestBody.altText
      - text: Edit the alt text of product {productId} image {imageId} to read {altText} without the v2 prefix.
        slots:
          productId: path.productId
          imageId: path.imageId
          altText: requestBody.altText
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productId}/images/{imageId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently remove a product image (unversioned)
      effect: destructive
      questions:
      - How do I permanently remove an image from a product via the unversioned path?
      - Is deleting a product image without the v2 prefix reversible?
      instructions:
      - text: Permanently remove unversioned image {imageId} from product {productId}.
        slots:
          imageId: path.imageId
          productId: path.productId
      - text: Delete product {productId}'s image {imageId} via the unversioned endpoint.
        slots:
          productId: path.productId
          imageId: path.imageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/products/{productId}/images/reorder'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the full display order of product images
      effect: write
      questions:
      - How do I reorder all of a product's images in one request?
      - Which image becomes the primary product image when I set a new order?
      instructions:
      - text: Reorder the images of product {productId} as {imageIds}.
        slots:
          productId: path.productId
          imageIds: requestBody.imageIds
      - text: Make product {productId}'s image order {imageIds}, first one as primary.
        slots:
          productId: path.productId
          imageIds: requestBody.imageIds
      method: generated
      generated: '2026-10-01'