API Evangelist conversational phrasing for Admin API V1 Punch Out Sessions API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Punch Out Sessions API
  version: 1.0.0
extends: openapi/optimizely-punch-out-sessions-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: 14
- target: $.paths['/api/v1/admin/PunchOutSessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List punchout sessions
      effect: read
      questions:
      - Which procurement punchout sessions have buyers opened against my commerce site?
      - Can I filter and sort punchout sessions with OData, for example by domain or creation date?
      instructions:
      - text: List all punchout sessions.
      - text: List punchout sessions matching {filter}, sorted by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PunchOutSessions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a punchout session record
      effect: write
      questions:
      - How do I record a new punchout session from a buyer's procurement system?
      - What identity and ship-to details are required to create a punchout session?
      instructions:
      - text: Create a punchout session for buyer cookie {buyerCookie} from {fromIdentity} to {toIdentity}.
        slots:
          buyerCookie: requestBody.buyerCookie
          fromIdentity: requestBody.fromIdentity
          toIdentity: requestBody.toIdentity
      - text: Open a punchout session in {punchOutSessionMode} mode that posts back to {browserFormPost}.
        slots:
          punchOutSessionMode: requestBody.punchOutSessionMode
          browserFormPost: requestBody.browserFormPost
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PunchOutSessions({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one punchout session
      effect: read
      questions:
      - How do I look up a single punchout session and its ship-to details?
      - Can I expand related data when reading one punchout session?
      instructions:
      - text: Get punchout session {id}.
        slots:
          id: path.id
      - text: Show punchout session {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PunchOutSessions({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a punchout session record
      effect: write
      questions:
      - How do I overwrite every field of an existing punchout session?
      - Does replacing a punchout session require resending all the identity and ship-to fields?
      instructions:
      - text: Replace punchout session {id} with a full record for buyer cookie {buyerCookie}.
        slots:
          id: path.id
          buyerCookie: requestBody.buyerCookie
      - text: Overwrite punchout session {id} entirely, shipping to {shipToName}.
        slots:
          id: path.id
          shipToName: requestBody.shipToName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PunchOutSessions({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a punchout session
      effect: destructive
      questions:
      - How do I remove a single punchout session record?
      - Can I guard a punchout session delete with an ETag so I don't remove a changed record?
      instructions:
      - text: Delete punchout session {id}.
        slots:
          id: path.id
      - text: Delete punchout session {id} only if its ETag is {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PunchOutSessions({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update fields on a punchout session
      effect: write
      questions:
      - Can I change just the ship-to address on a punchout session?
      - How do I link a punchout session to a customer order after the fact?
      instructions:
      - text: Update punchout session {id} to ship to {shipToStreet}, {shipToCity}.
        slots:
          id: path.id
          shipToStreet: requestBody.shipToStreet
          shipToCity: requestBody.shipToCity
      - text: Attach customer order {customerOrderId} to punchout session {id}.
        slots:
          customerOrderId: requestBody.customerOrderId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PunchOutSessions/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Call the Default function on punchout sessions
      effect: read
      questions:
      - What does the Default OData function on the punchout sessions set return?
      - Is there a default punchout session template I can read?
      instructions:
      - text: Call the Default function on punchout sessions.
      - text: Get the default punchout session entity.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/punchoutsessions/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete punchout sessions by ID
      effect: destructive
      questions:
      - Can I delete several punchout sessions in one call?
      - How do I clean out a batch of stale punchout sessions by their IDs?
      instructions:
      - text: Bulk delete punchout sessions {ids}.
        slots:
          ids: query.ids
      - text: 'Remove all of these punchout sessions at once: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/punchoutsessions({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a punchout session
      effect: read
      questions:
      - How do I read one custom property stored on a punchout session?
      - Can punchout sessions carry custom properties I can fetch individually?
      instructions:
      - text: Get custom property {custompropertyKey} of punchout session {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Read punchout session {key}'s custom field {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/punchoutsessions({key})/punchoutorderrequests({punchoutorderrequestKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order request from a punchout session
      effect: read
      questions:
      - How do I see the order request a punchout session sent back to procurement?
      - Can I fetch a specific punchout order request within a session?
      instructions:
      - text: Get order request {punchoutorderrequestKey} in punchout session {key}.
        slots:
          punchoutorderrequestKey: path.punchoutorderrequestKey
          key: path.key
      - text: Show the punchout order request {punchoutorderrequestKey} for session {key}.
        slots:
          punchoutorderrequestKey: path.punchoutorderrequestKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/punchoutsessions({key})/punchoutsessionaccesses({punchoutsessionaccessKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an access record for a punchout session
      effect: read
      questions:
      - Where can I see when and how a punchout session was accessed?
      - Can I look up a single session access entry for a punchout session?
      instructions:
      - text: Get access record {punchoutsessionaccessKey} of punchout session {key}.
        slots:
          punchoutsessionaccessKey: path.punchoutsessionaccessKey
          key: path.key
      - text: Show punchout session {key}'s access entry {punchoutsessionaccessKey}.
        slots:
          key: path.key
          punchoutsessionaccessKey: path.punchoutsessionaccessKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/punchoutsessions({key})/punchoutsessionextrinsics({punchoutsessionextrinsicKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an extrinsic value on a punchout session
      effect: read
      questions:
      - How do I read the cXML extrinsic values a buyer passed into a punchout session?
      - Can I fetch one extrinsic from a punchout session by its key?
      instructions:
      - text: Get extrinsic {punchoutsessionextrinsicKey} from punchout session {key}.
        slots:
          punchoutsessionextrinsicKey: path.punchoutsessionextrinsicKey
          key: path.key
      - text: Read the extrinsic {punchoutsessionextrinsicKey} sent with session {key}.
        slots:
          punchoutsessionextrinsicKey: path.punchoutsessionextrinsicKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/punchoutsessions({key})/punchoutsessionitemins({punchoutsessioniteminKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an inbound item on a punchout session
      effect: read
      questions:
      - Which items did the buyer bring into a punchout session for editing?
      - Can I read a single ItemIn line from a punchout session?
      instructions:
      - text: Get ItemIn line {punchoutsessioniteminKey} of punchout session {key}.
        slots:
          punchoutsessioniteminKey: path.punchoutsessioniteminKey
          key: path.key
      - text: Show inbound item {punchoutsessioniteminKey} for punchout session {key}.
        slots:
          punchoutsessioniteminKey: path.punchoutsessioniteminKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/punchoutsessions({key})/punchoutsetuprequests({punchoutsetuprequestKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the setup request of a punchout session
      effect: read
      questions:
      - How do I inspect the setup request that started a punchout session?
      - Can I retrieve the original PunchOutSetupRequest for troubleshooting a session?
      instructions:
      - text: Get setup request {punchoutsetuprequestKey} of punchout session {key}.
        slots:
          punchoutsetuprequestKey: path.punchoutsetuprequestKey
          key: path.key
      - text: Show the PunchOutSetupRequest {punchoutsetuprequestKey} behind session {key}.
        slots:
          punchoutsetuprequestKey: path.punchoutsetuprequestKey
          key: path.key
      method: generated
      generated: '2026-09-26'