# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Instacart Connect Fulfillment Delivery API
  version: 1.0.0
extends: openapi/instacart-delivery-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: 6
- target: $.paths['/v2/fulfillment/stores/delivery'].post
  update:
    x-apievangelist-phrasing:
      intent: Find stores that deliver to a location
      effect: read
      questions:
      - Which stores can deliver groceries to a given address?
      - Can I look up delivery stores by postal code or by latitude and longitude?
      - Are the stores that deliver sorted by distance from the customer?
      instructions:
      - text: Find stores that deliver to postal code {postal_code}.
        slots:
          postal_code: requestBody.postal_code
      - text: List delivery stores near latitude {latitude}, longitude {longitude}.
        slots:
          latitude: requestBody.latitude
          longitude: requestBody.longitude
      - text: Show which stores deliver to {address_line_1} in {city}, {state}.
        slots:
          address_line_1: requestBody.address_line_1
          city: requestBody.city
          state: requestBody.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/fulfillment/users/{user_id}/service_options/delivery'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview available delivery time slots
      effect: read
      questions:
      - What delivery windows can I show a customer before checkout?
      - Can I see delivery time options for a specific store and address?
      instructions:
      - text: Show available delivery time slots for user {user_id} from store {store_id}.
        slots:
          user_id: path.user_id
          store_id: requestBody.store_id
      - text: Preview delivery windows for user {user_id} to address {address}.
        slots:
          user_id: path.user_id
          address: requestBody.address
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/fulfillment/users/{user_id}/service_options/delivery/hold'].post
  update:
    x-apievangelist-phrasing:
      intent: Hold a delivery time slot
      effect: write
      questions:
      - How do I hold a delivery window for a customer before placing the order?
      - Does a reserved delivery slot expire if the order isn't created?
      instructions:
      - text: Reserve delivery slot {service_option_id} for user {user_id}.
        slots:
          service_option_id: requestBody.service_option_id
          user_id: path.user_id
      - text: Hold delivery window {service_option_id} for user {user_id} with cart {cart}.
        slots:
          service_option_id: requestBody.service_option_id
          user_id: path.user_id
          cart: requestBody.cart
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/fulfillment/users/{user_id}/orders/delivery'].post
  update:
    x-apievangelist-phrasing:
      intent: Place a delivery order
      effect: write
      questions:
      - How do I place a grocery delivery order after reserving a time slot?
      - Can I add driver instructions when creating a delivery order?
      instructions:
      - text: Create a delivery order for user {user_id} using hold {hold_id}.
        slots:
          user_id: path.user_id
          hold_id: requestBody.hold_id
      - text: Place a delivery order for user {user_id} on hold {hold_id} to {delivery_address} with note {delivery_instructions}.
        slots:
          user_id: path.user_id
          hold_id: requestBody.hold_id
          delivery_address: requestBody.delivery_address
          delivery_instructions: requestBody.delivery_instructions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/fulfillment/users/{user_id}/orders/{order_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up an order's status and details
      effect: read
      questions:
      - What is the current status of a customer's grocery order?
      - Can I see the items and fulfillment details of one order?
      instructions:
      - text: Get order {order_id} for user {user_id}.
        slots:
          order_id: path.order_id
          user_id: path.user_id
      - text: Check the status of user {user_id}'s order {order_id}.
        slots:
          user_id: path.user_id
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/fulfillment/users/{user_id}/orders/{order_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an order before a shopper takes it
      effect: destructive
      questions:
      - How do I cancel a delivery or pickup order?
      - Can an order still be canceled once a shopper has acknowledged it?
      instructions:
      - text: Cancel order {order_id} for user {user_id}.
        slots:
          order_id: path.order_id
          user_id: path.user_id
      - text: Call off user {user_id}'s order {order_id} while it is still brand new.
        slots:
          user_id: path.user_id
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'