# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for V2 Orders API
  version: 1.0.0
extends: openapi/northbeam-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: 4
- target: $.paths['/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: List orders in a date range
      effect: read
      questions:
      - Which orders has Northbeam received between two dates?
      - Can I pull back the orders I synced for last month?
      instructions:
      - text: List orders from {start_date} to {end_date}.
        slots:
          start_date: query.start_date
          end_date: query.end_date
      - text: Fetch the synced orders placed between {start_date} and {end_date}.
        slots:
          start_date: query.start_date
          end_date: query.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders'].post
  update:
    x-apievangelist-phrasing:
      intent: Upsert a batch of orders
      effect: write
      questions:
      - How do I send new orders from my shop into Northbeam?
      - Can I resubmit a full order to change its products or refunds?
      instructions:
      - text: Upsert this batch of full orders from my store.
      - text: Resubmit the complete order record, including products and refunds, to replace it.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update fields on existing orders
      effect: write
      questions:
      - How do I change just a few fields on orders I already synced to Northbeam?
      - Can I clear an optional field on an existing order by sending null?
      - What happens to the whole batch if one order in my partial update doesn't exist?
      - Are order tags and discount codes merged or replaced when I patch an order?
      instructions:
      - text: Patch the order tags on my existing synced orders, leaving every other field unchanged.
      - text: Partially update the discount codes on orders already in the app without resubmitting them.
      - text: Clear an optional field on existing orders by patching it to null.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders/aliases'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach alternate IDs to existing orders
      effect: write
      questions:
      - Can I link an alternate order ID to an order that's already been synced?
      - What happens if I add an order alias that already exists?
      - Which orders can receive aliases — do they have to exist first?
      instructions:
      - text: 'Add these alternate order IDs as aliases: {aliases}.'
        slots:
          aliases: requestBody.aliases
      - text: Attach aliases {aliases} to my existing orders so both IDs map to the same order.
        slots:
          aliases: requestBody.aliases
      method: generated
      generated: '2026-10-01'