# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Squarespace Orders API
  version: 1.0.0
extends: openapi/squarespace-orders-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: 8
- target: $.paths['/1.0/commerce/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter orders (1.0)
      effect: read
      questions:
      - How do I list orders for one customer with the versioned 1.0 orders API?
      - Can I filter 1.0 orders by fulfillment status or payment state?
      - Which orders were modified during last week, using the 1.0 endpoint?
      instructions:
      - text: List 1.0 orders for customer {customerId}.
        slots:
          customerId: query.customerId
      - text: List 1.0 orders with fulfillment status {fulfillmentStatus} and payment states {paymentStates}.
        slots:
          fulfillmentStatus: query.fulfillmentStatus
          paymentStates: query.paymentStates
      - text: List 1.0 orders modified between {modifiedAfter} and {modifiedBefore}.
        slots:
          modifiedAfter: query.modifiedAfter
          modifiedBefore: query.modifiedBefore
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/commerce/orders'].post
  update:
    x-apievangelist-phrasing:
      intent: Import a third-party channel order (1.0)
      effect: write
      questions:
      - How do I import an order placed on another sales channel into my store through the 1.0 API?
      - Can a 1.0 imported order skip deducting stock or skip the customer fulfillment email?
      instructions:
      - text: Import 1.0 order {externalOrderReference} from {channelName}, placed {createdOn}, items {lineItems}, total {grandTotal}, key {idempotencyKey}.
        slots:
          externalOrderReference: requestBody.externalOrderReference
          channelName: requestBody.channelName
          createdOn: requestBody.createdOn
          lineItems: requestBody.lineItems
          grandTotal: requestBody.grandTotal
          idempotencyKey: header.Idempotency-Key
      - text: Create a 1.0 order for {customerEmail} from {channelName} with inventory behavior {inventoryBehavior}.
        slots:
          customerEmail: requestBody.customerEmail
          channelName: requestBody.channelName
          inventoryBehavior: requestBody.inventoryBehavior
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/commerce/orders/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one order (1.0)
      effect: read
      questions:
      - How do I look up a single order by ID on the versioned 1.0 API?
      - What does a 1.0 order record contain?
      instructions:
      - text: Get 1.0 order {id}.
        slots:
          id: path.id
      - text: Show the details of order {id} from the 1.0 endpoint.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/commerce/orders/{id}/fulfillments'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark an order fulfilled (1.0)
      effect: write
      questions:
      - How do I mark an order as shipped with the 1.0 fulfillment endpoint?
      - Is the customer email optional when fulfilling an order through version 1.0?
      instructions:
      - text: Fulfill 1.0 order {id} with shipments {shipments}.
        slots:
          id: path.id
          shipments: requestBody.shipments
      - text: 'Mark 1.0 order {id} fulfilled, notify customer: {shouldSendNotification}.'
        slots:
          id: path.id
          shouldSendNotification: requestBody.shouldSendNotification
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: List orders (unversioned)
      effect: read
      questions:
      - Which orders were updated recently, via the unversioned orders path?
      - Can the unversioned order listing be filtered by fulfillment status?
      instructions:
      - text: Retrieve unversioned orders modified after {modifiedAfter}.
        slots:
          modifiedAfter: query.modifiedAfter
      - text: Retrieve unversioned orders with fulfillment status {fulfillmentStatus}.
        slots:
          fulfillmentStatus: query.fulfillmentStatus
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/orders'].post
  update:
    x-apievangelist-phrasing:
      intent: Import an order (unversioned)
      effect: write
      questions:
      - Does importing an order through the unversioned path charge the customer's card?
      - What addresses and totals must an unversioned imported order include?
      instructions:
      - text: Create an unversioned order for {customerEmail} with items {lineItems}, totals {totals}, billing {billingAddress} and shipping {shippingAddress}.
        slots:
          customerEmail: requestBody.customerEmail
          lineItems: requestBody.lineItems
          totals: requestBody.totals
          billingAddress: requestBody.billingAddress
          shippingAddress: requestBody.shippingAddress
      - text: Record external order {externalOrderReference} from channel {channel} for {customerEmail} without the 1.0 prefix.
        slots:
          externalOrderReference: requestBody.externalOrderReference
          channel: requestBody.channel
          customerEmail: requestBody.customerEmail
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/orders/{orderId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one order (unversioned)
      effect: read
      questions:
      - Can I see the line items, addresses and payment details of an order via the unversioned path?
      - How do I retrieve a specific order without the 1.0 prefix?
      instructions:
      - text: Retrieve unversioned order {orderId}.
        slots:
          orderId: path.orderId
      - text: Show line items and payment details for order {orderId} from the unversioned endpoint.
        slots:
          orderId: path.orderId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/commerce/orders/{orderId}/fulfillments'].post
  update:
    x-apievangelist-phrasing:
      intent: Fulfill line items with tracking (unversioned)
      effect: write
      questions:
      - How do I add tracking numbers when fulfilling an order via the unversioned path?
      - Can I fulfill specific line items through the unversioned fulfillment endpoint?
      instructions:
      - text: 'Fulfill unversioned order {orderId} with shipments {shipments}, send notification: {shouldSendNotification}.'
        slots:
          orderId: path.orderId
          shipments: requestBody.shipments
          shouldSendNotification: requestBody.shouldSendNotification
      - text: Record tracking {shipments} on order {orderId} without emailing the customer ({shouldSendNotification}).
        slots:
          shipments: requestBody.shipments
          orderId: path.orderId
          shouldSendNotification: requestBody.shouldSendNotification
      method: generated
      generated: '2026-10-01'