# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Products API
  version: 1.0.0
extends: openapi/optimizely-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: 58
- target: $.paths['/api/v1/admin/Products'].get
  update:
    x-apievangelist-phrasing:
      intent: List products in the commerce admin
      effect: read
      questions:
      - How do I pull every product record out of the Configured Commerce admin API?
      - Can I filter and sort the admin product list with OData options like $filter and $orderby?
      - Is there a way to page through the admin product catalog with $top and $skip?
      instructions:
      - text: List admin products matching the filter {filter}.
        slots:
          filter: query.$filter
      - text: Show the first {top} admin product records sorted by {orderby}.
        slots:
          top: query.$top
          orderby: query.$orderby
      - text: Count all product records in the commerce admin.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new product record
      effect: write
      questions:
      - How do I add a brand-new product to the commerce catalog through the admin API?
      - What fields are required when creating a product, like the ERP number and ERP description?
      - Can I set a list price and a sale window when I first create a product?
      instructions:
      - text: Create a product with ERP number {erpNumber} and ERP description {erpDescription}.
        slots:
          erpNumber: requestBody.erpNumber
          erpDescription: requestBody.erpDescription
      - text: Add new product {name} with ERP number {erpNumber}, description {erpDescription} and list price {basicListPrice}.
        slots:
          name: requestBody.name
          erpNumber: requestBody.erpNumber
          erpDescription: requestBody.erpDescription
          basicListPrice: requestBody.basicListPrice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one product record by id
      effect: read
      questions:
      - How do I look up a single product's full admin record when I have its id?
      - Can I expand related entities when fetching one product by its key?
      instructions:
      - text: Get the admin product record with id {id}.
        slots:
          id: path.id
      - text: Fetch product {id} and expand {expand}.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a product record entirely
      effect: write
      questions:
      - How do I overwrite an entire product record with a new full version?
      - Does replacing a product require sending the ERP number and ERP description again?
      instructions:
      - text: Replace product {id} with a full record using ERP number {erpNumber} and description {erpDescription}.
        slots:
          id: path.id
          erpNumber: requestBody.erpNumber
          erpDescription: requestBody.erpDescription
      - text: Overwrite all fields of product {id}, naming it {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single product record
      effect: destructive
      questions:
      - How do I permanently remove one product from the commerce admin by its id?
      - Can I guard a product deletion with an If-Match ETag so I don't delete a changed record?
      instructions:
      - text: Delete product {id}.
        slots:
          id: path.id
      - text: Delete product {id} only if its ETag still matches {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update selected fields on a product
      effect: write
      questions:
      - How do I change just a product's sale price without resending the whole record?
      - Can I mark an existing product as discontinued with a partial update?
      instructions:
      - text: Set the sale price of product {id} to {basicSalePrice}.
        slots:
          id: path.id
          basicSalePrice: requestBody.basicSalePrice
      - text: 'Mark product {id} as discontinued: {isDiscontinued}.'
        slots:
          id: path.id
          isDiscontinued: requestBody.isDiscontinued
      - text: Change the short description of product {id} to {shortDescription}.
        slots:
          id: path.id
          shortDescription: requestBody.shortDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Call the Default function on products
      effect: read
      questions:
      - What does the Default function on the admin Products entity set return?
      - Where do I get the default product record the admin API exposes?
      instructions:
      - text: Call the Default function on the admin Products set.
      - text: Fetch the default product entity from the commerce admin.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive products via the OData archive action
      effect: destructive
      questions:
      - How do I archive a batch of products using the Default.archive action?
      - Can I archive several products at once by passing their ids in a POST?
      instructions:
      - text: Archive products {ids} using the POST archive action.
        slots:
          ids: query.ids
      - text: Run the Default.archive action for product ids {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products/Default.isdiscontinued(productId={productId})'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a product is discontinued (OData function)
      effect: read
      questions:
      - How do I check through the Default.isdiscontinued OData function whether a product is discontinued?
      - Can the Default-namespace function tell me if a product was discontinued?
      instructions:
      - text: Call Default.isdiscontinued for product {productId}.
        slots:
          productId: path.productId
      - text: Use the OData isdiscontinued function to check product {productId}.
        slots:
          productId: path.productId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Products/Default.unitofmeasures(productId={productId})'].get
  update:
    x-apievangelist-phrasing:
      intent: List a product's units of measure (OData function)
      effect: read
      questions:
      - How do I get the units of measure for a product via the Default.unitofmeasures function?
      - Which OData function returns a product's selling units such as each or case?
      instructions:
      - text: Call Default.unitofmeasures for product {productId}.
        slots:
          productId: path.productId
      - text: Use the OData unitofmeasures function to list units for product {productId}.
        slots:
          productId: path.productId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products/isdiscontinued(productId={productId})'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a product is discontinued (plain route)
      effect: read
      questions:
      - Is there a plain lowercase products/isdiscontinued route to check a product's discontinued flag?
      - Can I tell whether an item is no longer sold without going through the OData Default namespace?
      instructions:
      - text: Check via the products/isdiscontinued route whether product {productId} is discontinued.
        slots:
          productId: path.productId
      - text: Tell me if product {productId} is discontinued using the non-OData route.
        slots:
          productId: path.productId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products/unitofmeasures(productId={productId})'].get
  update:
    x-apievangelist-phrasing:
      intent: List a product's units of measure (plain route)
      effect: read
      questions:
      - Is there a plain products/unitofmeasures route to list the units a product sells in?
      - Can I read a product's units of measure without calling the OData Default function?
      instructions:
      - text: List units of measure for product {productId} via the products/unitofmeasures route.
        slots:
          productId: path.productId
      - text: Show the non-OData unit list for product {productId}.
        slots:
          productId: path.productId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive products via the DELETE archive route
      effect: destructive
      questions:
      - Is there a DELETE route that archives products rather than deleting them outright?
      - How do I send a list of product ids to the products/archive endpoint?
      instructions:
      - text: Archive products {ids} through the DELETE products/archive route.
        slots:
          ids: query.ids
      - text: Send product ids {ids} to the archive route to retire them.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete products by id list
      effect: destructive
      questions:
      - How do I delete many products in one call by passing their ids?
      - Can I remove a whole batch of product records permanently with a single request?
      instructions:
      - text: Bulk delete products {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every product in the id list {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/attributevalues({attributevalueKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an attribute value assigned to a product
      effect: read
      questions:
      - Can I read one attribute value, like a color or size, that's assigned to a product?
      - Is a specific attribute value linked to a given product?
      instructions:
      - text: Get attribute value {attributevalueKey} on product {key}.
        slots:
          key: path.key
          attributevalueKey: path.attributevalueKey
      - text: Show product {key}'s assignment of attribute value {attributevalueKey}.
        slots:
          key: path.key
          attributevalueKey: path.attributevalueKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/badges({badgeKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a badge attached to a product
      effect: read
      questions:
      - Where can I see a specific badge, such as 'New' or 'Best Seller', attached to a product?
      - Can I confirm a particular badge is shown on one product?
      instructions:
      - text: Get badge {badgeKey} on product {key}.
        slots:
          key: path.key
          badgeKey: path.badgeKey
      - text: Show the badge {badgeKey} linked to product {key}.
        slots:
          key: path.key
          badgeKey: path.badgeKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/categories({categoryKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category a product belongs to
      effect: read
      questions:
      - Is a product placed in a particular catalog category?
      - Can I read one category record through a product's categories navigation?
      instructions:
      - text: Get category {categoryKey} of product {key}.
        slots:
          key: path.key
          categoryKey: path.categoryKey
      - text: Show product {key}'s membership in category {categoryKey}.
        slots:
          key: path.key
          categoryKey: path.categoryKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/customerproductsets({customerproductsetKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer product set containing a product
      effect: read
      questions:
      - How do I look up a customer product set that includes a given product?
      - Can I read one customer-specific product set through the product it contains?
      instructions:
      - text: Get customer product set {customerproductsetKey} for product {key}.
        slots:
          key: path.key
          customerproductsetKey: path.customerproductsetKey
      - text: Show the customer product set {customerproductsetKey} that product {key} is in.
        slots:
          key: path.key
          customerproductsetKey: path.customerproductsetKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/customervisibilityadditions({customerKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer a product is made visible to
      effect: read
      questions:
      - How do I check whether a product was explicitly made visible to a particular customer?
      - Can I read a customer visibility addition from the product side?
      instructions:
      - text: Get the visibility addition for customer {customerKey} on product {key}.
        slots:
          key: path.key
          customerKey: path.customerKey
      - text: Show whether customer {customerKey} was added to see product {key}.
        slots:
          key: path.key
          customerKey: path.customerKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/customervisibilityexceptions({customerKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer a product is hidden from
      effect: read
      questions:
      - How do I check if a product has been hidden from a specific customer?
      - Can I read a customer visibility exception that blocks one buyer from a product?
      instructions:
      - text: Get the visibility exception for customer {customerKey} on product {key}.
        slots:
          key: path.key
          customerKey: path.customerKey
      - text: Show whether product {key} is hidden from customer {customerKey}.
        slots:
          key: path.key
          customerKey: path.customerKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a product
      effect: read
      questions:
      - How do I read one custom property value stored on a product?
      - Can I fetch a single extension field that my team added to product records?
      instructions:
      - text: Get custom property {custompropertyKey} of product {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show the value of custom property {custompropertyKey} on product {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/dealers({dealerKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dealer that carries a product
      effect: read
      questions:
      - Which dealer record is linked to a product under a given dealer key?
      - Can I read one dealer record through the product's dealers list?
      instructions:
      - text: Get dealer {dealerKey} for product {key}.
        slots:
          key: path.key
          dealerKey: path.dealerKey
      - text: Show the dealer {dealerKey} that stocks product {key}.
        slots:
          key: path.key
          dealerKey: path.dealerKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/documents({documentKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a document attached to a product
      effect: read
      questions:
      - Where do I fetch a spec sheet or manual document attached to a product?
      - Can I read one product document record by its key?
      instructions:
      - text: Get document {documentKey} of product {key}.
        slots:
          key: path.key
          documentKey: path.documentKey
      - text: Show the attached document {documentKey} for product {key}.
        slots:
          key: path.key
          documentKey: path.documentKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/parentrelatedcategories({categoryrelatedproductKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category that lists a product as related
      effect: read
      questions:
      - How do I find a category that points to a product as one of its related products?
      - Can I read a parent category relationship for a product?
      instructions:
      - text: Get parent related category {categoryrelatedproductKey} for product {key}.
        slots:
          key: path.key
          categoryrelatedproductKey: path.categoryrelatedproductKey
      - text: Show the category relation {categoryrelatedproductKey} that references product {key}.
        slots:
          key: path.key
          categoryrelatedproductKey: path.categoryrelatedproductKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/parentrelatedproducts({productrelatedproductKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product that lists this one as related
      effect: read
      questions:
      - How do I see which other product references this product as a related item?
      - Can I read an inbound product relationship where this item is the child?
      instructions:
      - text: Get parent related product link {productrelatedproductKey} for product {key}.
        slots:
          key: path.key
          productrelatedproductKey: path.productrelatedproductKey
      - text: Show the inbound relation {productrelatedproductKey} pointing at product {key}.
        slots:
          key: path.key
          productrelatedproductKey: path.productrelatedproductKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/productimages({productimageKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an image of a product
      effect: read
      questions:
      - What does the record for one image in a product's gallery contain?
      - Can I fetch a single product image's details by its key?
      instructions:
      - text: Get image {productimageKey} of product {key}.
        slots:
          key: path.key
          productimageKey: path.productimageKey
      - text: Show the gallery image {productimageKey} for product {key}.
        slots:
          key: path.key
          productimageKey: path.productimageKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/productkitsections({productkitsectionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a kit section of a product
      effect: read
      questions:
      - What's in one section of a configurable product kit?
      - Can I inspect a single kit section that makes up a bundled product?
      instructions:
      - text: Get kit section {productkitsectionKey} of product {key}.
        slots:
          key: path.key
          productkitsectionKey: path.productkitsectionKey
      - text: Show the kit section {productkitsectionKey} inside product {key}.
        slots:
          key: path.key
          productkitsectionKey: path.productkitsectionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/productrelatedproducts({productrelatedproductKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a related product this product points to
      effect: read
      questions:
      - How do I read one outbound related-product link, like an accessory or cross-sell, on a product?
      - Can I check a specific product-to-product relationship this item defines?
      instructions:
      - text: Get related product link {productrelatedproductKey} defined on product {key}.
        slots:
          key: path.key
          productrelatedproductKey: path.productrelatedproductKey
      - text: Show the outbound related item {productrelatedproductKey} of product {key}.
        slots:
          key: path.key
          productrelatedproductKey: path.productrelatedproductKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/productunitofmeasures({productunitofmeasureKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one unit of measure record on a product
      effect: read
      questions:
      - How do I read one unit-of-measure record, such as a case, through a product's navigation?
      - Can I fetch a specific product unit of measure by its key from the product?
      instructions:
      - text: Get unit of measure record {productunitofmeasureKey} of product {key}.
        slots:
          key: path.key
          productunitofmeasureKey: path.productunitofmeasureKey
      - text: Show the unit record {productunitofmeasureKey} nested under product {key}.
        slots:
          key: path.key
          productunitofmeasureKey: path.productunitofmeasureKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/productwarehouses({productwarehouseKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product's warehouse record
      effect: read
      questions:
      - What does a product's stocking record for one warehouse look like?
      - Can I check a single warehouse entry for a product?
      instructions:
      - text: Get warehouse record {productwarehouseKey} of product {key}.
        slots:
          key: path.key
          productwarehouseKey: path.productwarehouseKey
      - text: Show the warehouse entry {productwarehouseKey} for product {key}.
        slots:
          key: path.key
          productwarehouseKey: path.productwarehouseKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/promotionresults({promotionresultKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a promotion result tied to a product
      effect: read
      questions:
      - Which promotion result applies to a particular product?
      - Can I read one promotion outcome record through the product?
      instructions:
      - text: Get promotion result {promotionresultKey} for product {key}.
        slots:
          key: path.key
          promotionresultKey: path.promotionresultKey
      - text: Show the promotion outcome {promotionresultKey} on product {key}.
        slots:
          key: path.key
          promotionresultKey: path.promotionresultKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/restrictiongroupadditions({restrictiongroupKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a restriction group addition on a product
      effect: read
      questions:
      - How do I check whether a product was explicitly added to a restriction group?
      - Can I read a restriction group addition record from the product?
      instructions:
      - text: Get restriction group addition {restrictiongroupKey} on product {key}.
        slots:
          key: path.key
          restrictiongroupKey: path.restrictiongroupKey
      - text: Show whether product {key} was added to restriction group {restrictiongroupKey}.
        slots:
          key: path.key
          restrictiongroupKey: path.restrictiongroupKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/restrictiongroupexceptions({restrictiongroupKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a restriction group exception on a product
      effect: read
      questions:
      - How do I check whether a product is exempted from a restriction group?
      - Can I read a restriction group exception that carves a product out?
      instructions:
      - text: Get restriction group exception {restrictiongroupKey} on product {key}.
        slots:
          key: path.key
          restrictiongroupKey: path.restrictiongroupKey
      - text: Show whether product {key} is excepted from restriction group {restrictiongroupKey}.
        slots:
          key: path.key
          restrictiongroupKey: path.restrictiongroupKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/restrictiongroups({restrictiongroupKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a restriction group a product belongs to
      effect: read
      questions:
      - Which restriction group governs who can buy this product?
      - Can I read the restriction group record itself through a product?
      instructions:
      - text: Get restriction group {restrictiongroupKey} assigned to product {key}.
        slots:
          key: path.key
          restrictiongroupKey: path.restrictiongroupKey
      - text: Show the purchase restriction group {restrictiongroupKey} for product {key}.
        slots:
          key: path.key
          restrictiongroupKey: path.restrictiongroupKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/ruleclauses({ruleclauseKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a rule clause applied to a product
      effect: read
      questions:
      - What does one rule clause attached to a product's rules say?
      - Can I inspect a single rule condition defined for a product?
      instructions:
      - text: Get rule clause {ruleclauseKey} of product {key}.
        slots:
          key: path.key
          ruleclauseKey: path.ruleclauseKey
      - text: Show the rule condition {ruleclauseKey} on product {key}.
        slots:
          key: path.key
          ruleclauseKey: path.ruleclauseKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/specifications({specificationKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specification of a product
      effect: read
      questions:
      - Can I read one specification section, like dimensions or materials, for a product?
      - Where is a single product specification record fetched by key?
      instructions:
      - text: Get specification {specificationKey} of product {key}.
        slots:
          key: path.key
          specificationKey: path.specificationKey
      - text: Show the spec entry {specificationKey} for product {key}.
        slots:
          key: path.key
          specificationKey: path.specificationKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/stylechildren({productKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a style child variant of a product
      effect: read
      questions:
      - How do I read one child variant of a style parent product in the admin API?
      - Can I fetch a specific style child, such as a size or color variant, from its parent?
      instructions:
      - text: Get style child {productKey} of parent product {key}.
        slots:
          key: path.key
          productKey: path.productKey
      - text: Show the admin record of variant {productKey} under style parent {key}.
        slots:
          key: path.key
          productKey: path.productKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/styletraitvalues({styletraitvalueKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a style trait value on a product
      effect: read
      questions:
      - How do I read the style trait value, like 'Red' or 'Large', set on a product?
      - Can I check which style trait value defines a particular variant?
      instructions:
      - text: Get style trait value {styletraitvalueKey} of product {key}.
        slots:
          key: path.key
          styletraitvalueKey: path.styletraitvalueKey
      - text: Show the trait value {styletraitvalueKey} that product {key} carries.
        slots:
          key: path.key
          styletraitvalueKey: path.styletraitvalueKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/subscriptionproducts({subscriptionproductKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subscription product linked to a product
      effect: read
      questions:
      - Which subscription product record is tied to a product?
      - Can I check a specific recurring-order subscription configuration on an item?
      instructions:
      - text: Get subscription product {subscriptionproductKey} for product {key}.
        slots:
          key: path.key
          subscriptionproductKey: path.subscriptionproductKey
      - text: Show the subscription link {subscriptionproductKey} on product {key}.
        slots:
          key: path.key
          subscriptionproductKey: path.subscriptionproductKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/taxexemptions({taxexemptionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tax exemption applied to a product
      effect: read
      questions:
      - How do I check whether a product carries a particular tax exemption?
      - Can I read one tax exemption record through a product?
      instructions:
      - text: Get tax exemption {taxexemptionKey} on product {key}.
        slots:
          key: path.key
          taxexemptionKey: path.taxexemptionKey
      - text: Show the tax exemption {taxexemptionKey} assigned to product {key}.
        slots:
          key: path.key
          taxexemptionKey: path.taxexemptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/websites({websiteKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a website a product is sold on
      effect: read
      questions:
      - How do I confirm a product is published to one particular storefront website?
      - Can I read a website record through the product's websites list?
      instructions:
      - text: Get website {websiteKey} for product {key}.
        slots:
          key: path.key
          websiteKey: path.websiteKey
      - text: Show the storefront site {websiteKey} that sells product {key}.
        slots:
          key: path.key
          websiteKey: path.websiteKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/products({key})/wishlistproducts({wishlistproductKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a wish list entry for a product
      effect: read
      questions:
      - Can I read one wish list entry that contains a given product?
      - Where is a specific shopper's saved-list line for an item stored?
      instructions:
      - text: Get wish list entry {wishlistproductKey} for product {key}.
        slots:
          key: path.key
          wishlistproductKey: path.wishlistproductKey
      - text: Show the saved-list line {wishlistproductKey} holding product {key}.
        slots:
          key: path.key
          wishlistproductKey: path.wishlistproductKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/products'].get
  update:
    x-apievangelist-phrasing:
      intent: Search storefront products (v1)
      effect: read
      questions:
      - How do I search the storefront catalog by keyword with the version 1 products endpoint?
      - Can I narrow a v1 product search to a price range or a set of brands?
      - Is it possible to return only stocked items in a v1 storefront product search?
      instructions:
      - text: Search v1 storefront products for {query}.
        slots:
          query: query.model.query
      - text: Find v1 products in category {categoryId} priced between {minimumPrice} and {maximumPrice}.
        slots:
          categoryId: query.model.categoryId
          minimumPrice: query.model.minimumPrice
          maximumPrice: query.model.maximumPrice
      - text: List v1 products with ERP numbers {erpNumbers}.
        slots:
          erpNumbers: query.model.erpNumbers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/products/{productId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a storefront product (v1)
      effect: read
      questions:
      - How do I load one product's storefront detail page data with the v1 API?
      - Can a v1 product lookup also add the item to the shopper's recently viewed list?
      instructions:
      - text: Get v1 storefront product {productId}.
        slots:
          productId: path.productId
      - text: Load v1 product {productId} in unit of measure {unitOfMeasure} for quantity {qtyOrdered}.
        slots:
          productId: path.productId
          unitOfMeasure: query.parameter.unitOfMeasure
          qtyOrdered: query.parameter.qtyOrdered
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/products/{productId}/crosssells'].get
  update:
    x-apievangelist-phrasing:
      intent: Get cross-sell products for a product
      effect: read
      questions:
      - What cross-sell suggestions show alongside a product?
      - Which products does the storefront recommend as cross-sells for an item?
      instructions:
      - text: Get cross-sells for product {productId}.
        slots:
          productId: path.productId
      - text: List the recommended add-on products for {productId}.
        slots:
          productId: path.productId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/products/{productId}/price'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the price of a product
      effect: read
      questions:
      - How do I get the real-time price a shopper would pay for a product?
      - Does the price change if I ask for a different unit of measure or order quantity?
      instructions:
      - text: Get the price of product {productId}.
        slots:
          productId: path.productId
      - text: Price product {productId} for {qtyOrdered} units in {unitOfMeasure}.
        slots:
          productId: path.productId
          qtyOrdered: query.productPriceModel.qtyOrdered
          unitOfMeasure: query.productPriceModel.unitOfMeasure
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/products/{productId}/availability'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a product's inventory availability
      effect: read
      questions:
      - Is a product in stock right now?
      - Can the availability check include inventory from alternate warehouses?
      instructions:
      - text: Check availability for product {productId}.
        slots:
          productId: path.productId
      - text: 'Check stock for product {productId} including alternate inventory: {includeAlternateInventory}.'
        slots:
          productId: path.productId
          includeAlternateInventory: query.productAvailabilityParameter.includeAlternateInventory
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/products/batchget'].post
  update:
    x-apievangelist-phrasing:
      intent: Batch look up products by extended name
      effect: read
      questions:
      - How do I fetch several products at once by their extended names?
      - Can I look up a batch of items in a single POST instead of one call per product?
      instructions:
      - text: Batch get products with extended names {extendedNames}.
        slots:
          extendedNames: requestBody.extendedNames
      - text: 'Look up all of these products by extended name in one request: {extendedNames}.'
        slots:
          extendedNames: requestBody.extendedNames
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/products/feederData'].get
  update:
    x-apievangelist-phrasing:
      intent: Get v1 product feeder data
      effect: read
      questions:
      - What does the v1 products feederData endpoint return?
      - Where can I pull the v1 product feeder data sample set?
      instructions:
      - text: Get the v1 product feeder data.
      - text: Fetch the feederData payload from the version 1 products endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/products'].get
  update:
    x-apievangelist-phrasing:
      intent: Search storefront products (v2)
      effect: read
      questions:
      - How do I search products with the newer v2 storefront endpoint using page tokens?
      - Can a v2 product search include products from subcategories of a category?
      - Is there a way to search by product numbers in the v2 products API?
      instructions:
      - text: Search v2 storefront products for {search}.
        slots:
          search: query.model.search
      - text: 'List v2 products in category {categoryId} including subcategories: {includeProductsInSubCategories}.'
        slots:
          categoryId: query.model.categoryId
          includeProductsInSubCategories: query.model.includeProductsInSubCategories
      - text: Find v2 products with product numbers {productNumbers}.
        slots:
          productNumbers: query.model.productNumbers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/products/{ProductId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a storefront product (v2)
      effect: read
      questions:
      - How do I fetch one product through the v2 storefront API with its attributes?
      - Can I get a v2 product in the context of a specific category?
      instructions:
      - text: Get v2 product {ProductId}.
        slots:
          ProductId: path.ProductId
      - text: 'Get v2 product {ProductId} with attributes included: {includeAttributes}.'
        slots:
          ProductId: path.ProductId
          includeAttributes: query.parameter.includeAttributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/products/{productId}/alsopurchased'].get
  update:
    x-apievangelist-phrasing:
      intent: List products also purchased with a product
      effect: read
      questions:
      - What do other customers usually buy together with this product?
      - Can I page through the 'customers also purchased' list for an item?
      instructions:
      - text: List products also purchased with {productId}.
        slots:
          productId: path.productId
      - text: Show page {page} of the also-purchased items for product {productId}.
        slots:
          productId: path.productId
          page: query.parameter.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/products/{productId}/relatedproducts'].get
  update:
    x-apievangelist-phrasing:
      intent: List a product's related products (v2)
      effect: read
      questions:
      - How do I list related products, such as accessories, for an item in the v2 storefront API?
      - Can I filter a product's related items by relationship type?
      instructions:
      - text: List v2 related products for {productId}.
        slots:
          productId: path.productId
      - text: List products related to {productId} by relationship {relationship}.
        slots:
          productId: path.productId
          relationship: query.parameter.relationship
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/products/{productId}/variantchildren'].get
  update:
    x-apievangelist-phrasing:
      intent: List a product's variants
      effect: read
      questions:
      - How do I list all the variants, like each size and color, of a style product?
      - Can I page through a parent product's variant children on the storefront?
      instructions:
      - text: List variant children of product {productId}.
        slots:
          productId: path.productId
      - text: Show {pageSize} variants per page for product {productId}.
        slots:
          productId: path.productId
          pageSize: query.parameter.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/products/{productId}/variantchildren/{variantChildId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one variant of a product
      effect: read
      questions:
      - How do I load a single variant of a style product on the storefront?
      - Can I include attributes when fetching one variant child?
      instructions:
      - text: Get variant {variantChildId} of product {productId}.
        slots:
          productId: path.productId
          variantChildId: path.variantChildId
      - text: Load storefront variant {variantChildId} of {productId} with its attributes.
        slots:
          productId: path.productId
          variantChildId: path.variantChildId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/products/feederData/productWithMostAttributes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the product with the most attributes
      effect: read
      questions:
      - Which product in the catalog has the most attributes defined?
      - Where do I get the feeder product with the richest attribute set?
      instructions:
      - text: Get the product with the most attributes.
      - text: Fetch the feeder product carrying the largest attribute count.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/products/feederData/productWithMostVariants'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the product with the most variants
      effect: read
      questions:
      - Which product in the catalog has the most variants?
      - Where do I get the feeder product with the biggest variant list?
      instructions:
      - text: Get the product with the most variants.
      - text: Fetch the feeder product carrying the largest number of variant children.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/objects/products'].post
  update:
    x-apievangelist-phrasing:
      intent: Update product metadata in the data platform
      effect: write
      questions:
      - How do I push updated product metadata to the data platform as my inventory changes?
      - Can I sync product objects in Optimizely Data Platform whenever my catalog updates?
      instructions:
      - text: Update product objects in the data platform with the latest inventory metadata.
      - text: Sync my changed products to the data platform products object.
      method: generated
      generated: '2026-09-26'