# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Storefront API V1 Carts API
  version: 1.0.0
extends: openapi/optimizely-carts-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: 18
- target: $.paths['/api/v1/carts/{cartId}/promotions'].get
  update:
    x-apievangelist-phrasing:
      intent: List promotions applied to a cart
      effect: read
      questions:
      - Which promotions are currently applied to a shopper's cart?
      - Can I see every promo code that has been used on a cart?
      instructions:
      - text: List the promotions applied to cart {cartId}.
        slots:
          cartId: path.cartId
      - text: Show all promo codes on cart {cartId}.
        slots:
          cartId: path.cartId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/promotions'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply a promotion code to a cart
      effect: write
      questions:
      - How do I apply a promo code to a customer's cart?
      - What happens when I add a promotion code that doesn't qualify for the cart?
      instructions:
      - text: Apply promo code {promotionCode} to cart {cartId}.
        slots:
          cartId: path.cartId
          promotionCode: requestBody.promotionCode
      - text: Add promotion code {promotionCode} to cart {cartId} for order line {orderLineId}.
        slots:
          cartId: path.cartId
          promotionCode: requestBody.promotionCode
          orderLineId: requestBody.orderLineId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/promotions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all promotions from a cart
      effect: destructive
      questions:
      - How do I strip every promo code off a cart at once?
      - Can I clear all applied promotions from a cart in one call?
      instructions:
      - text: Remove all promotions from cart {cartId}.
        slots:
          cartId: path.cartId
      - text: Clear every applied promo code on cart {cartId}.
        slots:
          cartId: path.cartId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/promotions/{promotionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one promotion applied to a cart
      effect: read
      questions:
      - What discount amount did a specific promotion give on a cart?
      - Can I look up a single promotion that was applied to a cart?
      instructions:
      - text: Get promotion {promotionId} on cart {cartId}.
        slots:
          cartId: path.cartId
          promotionId: path.promotionId
      - text: Show how much promotion {promotionId} took off cart {cartId}.
        slots:
          cartId: path.cartId
          promotionId: path.promotionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/promotions/{promotionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one promotion from a cart
      effect: destructive
      questions:
      - How do I remove just one promo code from a cart and keep the others?
      - Can a single applied promotion be taken off a shopper's cart?
      instructions:
      - text: Remove promotion {promotionId} from cart {cartId}.
        slots:
          cartId: path.cartId
          promotionId: path.promotionId
      - text: Take promo {promotionId} off cart {cartId} but leave the other promotions.
        slots:
          cartId: path.cartId
          promotionId: path.promotionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts'].get
  update:
    x-apievangelist-phrasing:
      intent: List carts and orders in progress
      effect: read
      questions:
      - How do I find all carts for a particular bill-to account?
      - Can I filter carts by status and date range?
      - Which carts have an order total over a certain amount?
      instructions:
      - text: List carts with status {status}.
        slots:
          status: query.parameter.status
      - text: Show carts for bill-to {billToId} created between {fromDate} and {toDate}.
        slots:
          billToId: query.parameter.billToId
          fromDate: query.parameter.fromDate
          toDate: query.parameter.toDate
      - text: Find the cart with order number {orderNumber}.
        slots:
          orderNumber: query.parameter.orderNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new cart
      effect: write
      questions:
      - How do I start a new cart for a customer's bill-to and ship-to addresses?
      - Can I create a cart tied to a VMI location?
      instructions:
      - text: Create a new cart for bill-to {billToId} and ship-to {shipToId}.
        slots:
          billToId: requestBody.billToId
          shipToId: requestBody.shipToId
      - text: Start a cart for VMI location {vmiLocationId} with notes {notes}.
        slots:
          vmiLocationId: requestBody.vmiLocationId
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a cart's details and totals
      effect: read
      questions:
      - What's the grand total, tax and shipping on a specific cart?
      - Can I check whether a cart is ready to check out?
      instructions:
      - text: Get cart {cartId}.
        slots:
          cartId: path.cartId
      - text: Show the totals and status of cart {cartId}.
        slots:
          cartId: path.cartId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a cart
      effect: destructive
      questions:
      - How do I throw away an entire cart?
      - Can I delete a saved cart that's no longer needed?
      instructions:
      - text: Delete cart {cartId}.
        slots:
          cartId: path.cartId
      - text: Discard cart {cartId} entirely.
        slots:
          cartId: path.cartId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a cart or submit it as an order
      effect: write
      questions:
      - How do I set the PO number and shipping method on a cart?
      - Can I submit a cart by changing its status?
      - Where do I set the requested delivery date on a cart?
      instructions:
      - text: Set PO number {poNumber} on cart {cartId}.
        slots:
          cartId: path.cartId
          poNumber: requestBody.poNumber
      - text: Change the status of cart {cartId} to {status}.
        slots:
          cartId: path.cartId
          status: requestBody.status
      - text: Update cart {cartId} notes to {notes}.
        slots:
          cartId: path.cartId
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/cartlines'].get
  update:
    x-apievangelist-phrasing:
      intent: List the line items in a cart
      effect: read
      questions:
      - What products are in a customer's cart right now?
      - Can I page through the line items of a large cart?
      instructions:
      - text: List the lines in cart {cartId}.
        slots:
          cartId: path.cartId
      - text: Show page {page} of cart {cartId} line items.
        slots:
          cartId: path.cartId
          page: query.cartLineCollectionParameter.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/cartlines'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a product to a cart
      effect: write
      questions:
      - How do I add a product with a quantity to a cart?
      - Can I add an item to a cart with a line note?
      instructions:
      - text: Add {qtyOrdered} of product {productId} to cart {cartId}.
        slots:
          cartId: path.cartId
          productId: requestBody.productId
          qtyOrdered: requestBody.qtyOrdered
      - text: Put product {productId} in cart {cartId} with quantity {qtyOrdered} and note {notes}.
        slots:
          cartId: path.cartId
          productId: requestBody.productId
          qtyOrdered: requestBody.qtyOrdered
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/cartlines'].delete
  update:
    x-apievangelist-phrasing:
      intent: Empty all lines from a cart
      effect: destructive
      questions:
      - How do I empty a cart without deleting the cart itself?
      - Can I remove every line item from a cart at once?
      instructions:
      - text: Empty all line items from cart {cartId}.
        slots:
          cartId: path.cartId
      - text: Remove every product line from cart {cartId} but keep the cart.
        slots:
          cartId: path.cartId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/cartlines/{cartLineId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one line item in a cart
      effect: read
      questions:
      - What price and availability does one cart line show?
      - Can I look up a single line item in a cart?
      instructions:
      - text: Get line {cartLineId} in cart {cartId}.
        slots:
          cartId: path.cartId
          cartLineId: path.cartLineId
      - text: Show pricing for cart line {cartLineId} of cart {cartId}.
        slots:
          cartId: path.cartId
          cartLineId: path.cartLineId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/cartlines/{cartLineId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one line item from a cart
      effect: destructive
      questions:
      - How do I remove one product from a cart?
      - Can I delete a single cart line and leave the rest?
      instructions:
      - text: Remove line {cartLineId} from cart {cartId}.
        slots:
          cartId: path.cartId
          cartLineId: path.cartLineId
      - text: Delete cart line {cartLineId} in cart {cartId}.
        slots:
          cartId: path.cartId
          cartLineId: path.cartLineId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/cartlines/{cartLineId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change quantity or notes on a cart line
      effect: write
      questions:
      - How do I change the quantity of an item already in the cart?
      - Can I update the note or cost code on an existing cart line?
      instructions:
      - text: Change cart line {cartLineId} in cart {cartId} to quantity {qtyOrdered}.
        slots:
          cartId: path.cartId
          cartLineId: path.cartLineId
          qtyOrdered: requestBody.qtyOrdered
      - text: Set the cost code on existing line {cartLineId} of cart {cartId} to {costCode}.
        slots:
          cartId: path.cartId
          cartLineId: path.cartLineId
          costCode: requestBody.costCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/cartlines/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Add several products to a cart at once
      effect: write
      questions:
      - How do I bulk add many products to a cart in a single request?
      - What tells me if not every item in a batch made it into the cart?
      instructions:
      - text: Batch add these lines {cartLines} to cart {cartId}.
        slots:
          cartId: path.cartId
          cartLines: requestBody.cartLines
      - text: Add multiple products {cartLines} to cart {cartId} in one request.
        slots:
          cartId: path.cartId
          cartLines: requestBody.cartLines
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/carts/{cartId}/cartlines/wishlist/{wishListId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a wish list's items to a cart
      effect: write
      questions:
      - How do I move everything from a wish list into a cart?
      - Can a shared list's items be added to the cart in one step?
      instructions:
      - text: Add all items from wish list {wishListId} to cart {cartId}.
        slots:
          cartId: path.cartId
          wishListId: path.wishListId
      - text: Copy wish list {wishListId} into cart {cartId}.
        slots:
          cartId: path.cartId
          wishListId: path.wishListId
      method: generated
      generated: '2026-09-26'