# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Shopify Orders API
  version: 1.0.0
extends: openapi/shopify-orders-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 23
- target: $.paths['/orders.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List recent orders with filters
      effect: read
      questions:
      - Which of my store's orders from the last 60 days are still unfulfilled?
      - Can I include orders of any status, not just open ones, when listing?
      - What date filters can I use to list orders placed in a specific window?
      instructions:
      - text: List orders with status {status} created after {created_at_min}.
        slots:
          status: query.status
          created_at_min: query.created_at_min
      - text: Show orders whose payment status is {financial_status}, up to {limit} of them.
        slots:
          financial_status: query.financial_status
          limit: query.limit
      - text: List orders with fulfillment status {fulfillment_status} updated since {updated_at_min}.
        slots:
          fulfillment_status: query.fulfillment_status
          updated_at_min: query.updated_at_min
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orders.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Record an order from an external channel
      effect: write
      questions:
      - How do I import a sale made on another channel as an order in Shopify?
      - Does creating an order through the API charge the customer's card?
      instructions:
      - text: 'Create an order from this sale: {order}.'
        slots:
          order: requestBody.order
      - text: Record an external-channel sale as a new order with details {order}.
        slots:
          order: requestBody.order
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orders/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count orders matching filters
      effect: read
      questions:
      - How many orders did I get since the start of the month?
      - Can I count only the orders that are paid but not yet shipped?
      instructions:
      - text: Count orders created since {created_at_min}.
        slots:
          created_at_min: query.created_at_min
      - text: Tell me how many orders have payment status {financial_status} and fulfillment status {fulfillment_status}.
        slots:
          financial_status: query.financial_status
          fulfillment_status: query.fulfillment_status
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orders/{order_id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one order's details
      effect: read
      questions:
      - What line items and totals are on a specific order?
      - Can I fetch only certain fields of a single order?
      instructions:
      - text: Show me order {order_id}.
        slots:
          order_id: path.order_id
      - text: Get order {order_id} with only the fields {fields}.
        slots:
          order_id: path.order_id
          fields: query.fields
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orders/{order_id}.json'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an order's note, tags or contact info
      effect: write
      questions:
      - Can I change the shipping address on an order that's already been placed?
      - Which parts of an existing order, like tags or note, can be edited?
      instructions:
      - text: Update order {order_id} with {order}.
        slots:
          order_id: path.order_id
          order: requestBody.order
      - text: Change the note and tags on existing order {order_id} to {order}.
        slots:
          order_id: path.order_id
          order: requestBody.order
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orders/{order_id}.json'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an order
      effect: destructive
      questions:
      - Why can't I delete an order that was paid through an online gateway?
      - How do I permanently delete an order record from my store?
      instructions:
      - text: Delete order {order_id}.
        slots:
          order_id: path.order_id
      - text: Permanently remove order {order_id} from the store.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orders/{order_id}/cancel.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an order and optionally restock
      effect: destructive
      questions:
      - How do I cancel an order and put the items back in stock?
      - Can I email the customer when I cancel their order?
      instructions:
      - text: Cancel order {order_id} with reason {reason}.
        slots:
          order_id: path.order_id
          reason: requestBody.reason
      - text: Cancel order {order_id}, restock items ({restock}) and send the cancellation email ({email}).
        slots:
          order_id: path.order_id
          restock: requestBody.restock
          email: requestBody.email
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orders/{order_id}/close.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Close an order as completed
      effect: destructive
      questions:
      - Can I mark a finished order as closed once it's done?
      - What does closing an order do to its status?
      instructions:
      - text: Close order {order_id}.
        slots:
          order_id: path.order_id
      - text: Mark order {order_id} as completed.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orders/{order_id}/open.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-open a closed order
      effect: write
      questions:
      - Can I bring back an order I closed by mistake?
      - Is it possible to reopen an order that was marked completed?
      instructions:
      - text: Re-open closed order {order_id}.
        slots:
          order_id: path.order_id
      - text: Open order {order_id} back up after it was closed.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/orders/{order_id}/cancel.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an order with a refund amount (2020-01)
      effect: destructive
      questions:
      - How do I cancel a multi-currency order and refund a set amount with the 2020-01 API?
      - Which cancellation reasons does version 2020-01 accept — customer, inventory, fraud, declined, other?
      instructions:
      - text: Cancel order {order_id} on 2020-01 and refund {amount} {currency}.
        slots:
          order_id: path.order_id
          amount: query.amount
          currency: query.currency
      - text: Using API version 2020-01, cancel order {order_id} for reason {reason} and notify the customer ({email}).
        slots:
          order_id: path.order_id
          reason: query.reason
          email: query.email
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-04/orders/{order_id}/cancel.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an order with a refund amount (2020-04)
      effect: destructive
      questions:
      - Can I void payment while cancelling an order on release 2020-04?
      - Does the 2020-04 cancel call need a currency when I pass a refund amount?
      instructions:
      - text: Through 2020-04, cancel order {order_id}, refunding {amount} in {currency}.
        slots:
          order_id: path.order_id
          amount: query.amount
          currency: query.currency
      - text: Cancel order {order_id} as {reason} via the 2020-04 endpoint, email flag {email}.
        slots:
          order_id: path.order_id
          reason: query.reason
          email: query.email
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/orders/{order_id}/refunds.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a refund on an order (2020-01)
      effect: write
      questions:
      - How do I refund specific line items on an order with the 2020-01 API?
      - Can version 2020-01 notify the customer when I issue a refund?
      instructions:
      - text: Refund line items {refund_line_items} on order {order_id} using 2020-01.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: On 2020-01, issue a refund for order {order_id} and set customer notification to {notify}.
        slots:
          order_id: path.order_id
          notify: query.notify
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/orders/{order_id}/refunds/calculate.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview what a refund would be (2020-01)
      effect: read
      questions:
      - How do I work out how much a refund would be before issuing it with the 2020-01 API?
      - Can version 2020-01 calculate refundable shipping for an order?
      instructions:
      - text: Calculate the refund for line items {refund_line_items} on order {order_id} using 2020-01.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: On 2020-01, estimate refundable shipping {shipping} for order {order_id}.
        slots:
          order_id: path.order_id
          shipping: query.shipping
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-04/orders/{order_id}/refunds.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a refund on an order (2020-04)
      effect: write
      questions:
      - Can I refund shipping costs as well as items using release 2020-04?
      - Is it possible to attach a note to a refund in 2020-04?
      instructions:
      - text: Refund shipping {shipping} in {currency} on order {order_id} via 2020-04.
        slots:
          order_id: path.order_id
          shipping: query.shipping
          currency: query.currency
      - text: Using 2020-04, refund items {refund_line_items} from order {order_id} with note {note}.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
          note: query.note
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-04/orders/{order_id}/refunds/calculate.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview what a refund would be (2020-04)
      effect: read
      questions:
      - Can I get the transactions a refund would need, without refunding, on release 2020-04?
      - Does the 2020-04 refund calculation need a currency when shipping is included?
      instructions:
      - text: Preview a refund of items {refund_line_items} from order {order_id} via 2020-04.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: Using 2020-04, compute the shipping refund {shipping} in {currency} for order {order_id}.
        slots:
          order_id: path.order_id
          shipping: query.shipping
          currency: query.currency
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-07/orders/{order_id}/refunds.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a refund on an order (2020-07)
      effect: write
      questions:
      - Is there a 2020-07 endpoint to create a refund for an order?
      - Can I explain why the refunded amount differs from the calculated one on 2020-07?
      instructions:
      - text: Create a refund on order {order_id} processing transactions {transactions} through 2020-07.
        slots:
          order_id: path.order_id
          transactions: query.transactions
      - text: Refund order {order_id} on 2020-07 with discrepancy reason {discrepancy_reason}.
        slots:
          order_id: path.order_id
          discrepancy_reason: query.discrepancy_reason
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-07/orders/{order_id}/refunds/calculate.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview what a refund would be (2020-07)
      effect: read
      questions:
      - Is there a 2020-07 endpoint that calculates a refund without creating it?
      - Can I check refund totals for returned items on 2020-07?
      instructions:
      - text: Work out refund totals for returned items {refund_line_items} on order {order_id} through 2020-07.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: Dry-run a shipping refund of {shipping} for order {order_id} on the 2020-07 API.
        slots:
          order_id: path.order_id
          shipping: query.shipping
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-10/orders/{order_id}/refunds.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a refund on an order
      effect: write
      questions:
      - What call creates a refund on an order in the 2020-10 Admin API?
      - Can I choose which currency a refund is issued in on 2020-10?
      instructions:
      - text: Refund line items {refund_line_items} of order {order_id} with the 2020-10 Admin API.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: Using 2020-10, refund {shipping} of shipping on order {order_id} in {currency}.
        slots:
          order_id: path.order_id
          shipping: query.shipping
          currency: query.currency
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-10/orders/{order_id}/refunds/calculate.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview what a refund would be
      effect: read
      questions:
      - What call calculates a refund in the 2020-10 Admin API?
      - Before refunding on 2020-10, can I see what the refund transactions would be?
      instructions:
      - text: Calculate a refund for items {refund_line_items} of order {order_id} with the 2020-10 Admin API.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: Using 2020-10, preview the shipping refund {shipping} in {currency} on order {order_id}.
        slots:
          order_id: path.order_id
          shipping: query.shipping
          currency: query.currency
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2021-01/orders/{order_id}/refunds.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a refund on an order (2021-01)
      effect: write
      questions:
      - Does the January 2021 (2021-01) API let me issue refunds?
      - Can I refund an order without emailing the customer on 2021-01?
      instructions:
      - text: Issue a quiet refund on order {order_id} via the 2021-01 version, notify set to {notify}.
        slots:
          order_id: path.order_id
          notify: query.notify
      - text: With API version 2021-01, refund order {order_id} by processing refund transactions {transactions}.
        slots:
          order_id: path.order_id
          transactions: query.transactions
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2021-01/orders/{order_id}/refunds/calculate.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview what a refund would be (2021-01)
      effect: read
      questions:
      - Does the January 2021 (2021-01) API have a refund calculator?
      - Can I quote a customer their refund before processing it on 2021-01?
      instructions:
      - text: Quote the refund on order {order_id} for lines {refund_line_items} via the 2021-01 version.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: With API version 2021-01, calculate refundable shipping {shipping} for order {order_id}.
        slots:
          order_id: path.order_id
          shipping: query.shipping
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/unstable/orders/{order_id}/refunds.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a refund on an order (unstable)
      effect: write
      questions:
      - Can I create an order refund through the unstable Admin API?
      - Does the unstable version accept refund line items with restock instructions?
      instructions:
      - text: Refund items {refund_line_items} on order {order_id} against the unstable API.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: Use the unstable endpoint to refund order {order_id}, noting {note}, for items {refund_line_items}.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
          note: query.note
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/unstable/orders/{order_id}/refunds/calculate.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview what a refund would be (unstable)
      effect: read
      questions:
      - Can I calculate a refund through the unstable Admin API?
      - Does the unstable version compute refund amounts for shipping too?
      instructions:
      - text: Calculate a refund for order {order_id} lines {refund_line_items} against the unstable API.
        slots:
          order_id: path.order_id
          refund_line_items: query.refund_line_items
      - text: Use the unstable endpoint to estimate a {shipping} shipping refund in {currency} for order {order_id}.
        slots:
          order_id: path.order_id
          shipping: query.shipping
          currency: query.currency
      method: generated
      generated: '2026-09-24'