# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Klarna Merchant Card Service Merchantcard API
  version: 1.0.0
extends: openapi/klarna-merchant-card-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: 7
- target: $.paths['/merchantcard/v3/promises'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a virtual card promise for an order
      effect: write
      questions:
      - How do I request virtual credit cards to pay a supplier for an order?
      - What happens to the previous card promise when I create a new one for the same order?
      instructions:
      - text: Create a card promise for order {order_id} with cards {cards}.
        slots:
          order_id: requestBody.order_id
          cards: requestBody.cards
      - text: Promise virtual cards {cards} for order {order_id}.
        slots:
          cards: requestBody.cards
          order_id: requestBody.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/merchantcard/v3/promises/{promise_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a virtual card promise
      effect: read
      questions:
      - Can I look up which cards were promised in a card promise?
      - Where do I check the details of an existing virtual card promise?
      instructions:
      - text: Get card promise {promise_id}.
        slots:
          promise_id: path.promise_id
      - text: Show the details of virtual card promise {promise_id}.
        slots:
          promise_id: path.promise_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/merchantcard/v3/settlements'].post
  update:
    x-apievangelist-phrasing:
      intent: Settle virtual cards for a completed order
      effect: write
      questions:
      - How do I get the actual virtual card numbers once an order is complete?
      - Can I settle cards for an order without passing a promise id?
      instructions:
      - text: Create a card settlement for order {order_id} with key {key_id}.
        slots:
          order_id: requestBody.order_id
          key_id: requestBody.key_id
      - text: Settle promise {promise_id} for completed order {order_id} using key {key_id}.
        slots:
          promise_id: requestBody.promise_id
          order_id: requestBody.order_id
          key_id: requestBody.key_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/merchantcard/v3/settlements/{settlement_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a virtual card settlement by id
      effect: read
      questions:
      - Can I retrieve an existing card settlement using its settlement id?
      - Why does reading a settlement require a key id header?
      instructions:
      - text: Get card settlement {settlement_id} with key {KeyId}.
        slots:
          settlement_id: path.settlement_id
          KeyId: header.KeyId
      - text: Retrieve the virtual cards in settlement {settlement_id} using key {KeyId}.
        slots:
          settlement_id: path.settlement_id
          KeyId: header.KeyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/merchantcard/v3/settlements/order/{order_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the card settlement for an order
      effect: read
      questions:
      - If I only have the order id, can I find its virtual card settlement?
      - Where do I look up the settled cards belonging to a particular order?
      instructions:
      - text: Get the card settlement for order {order_id} with key {KeyId}.
        slots:
          order_id: path.order_id
          KeyId: header.KeyId
      - text: Find the virtual card settlement of order {order_id} using key {KeyId}.
        slots:
          order_id: path.order_id
          KeyId: header.KeyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/merchantcard/v3/orders/{order_id}/cancel-request'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a virtual card order cancellation
      effect: read
      questions:
      - Has my cancellation request for a virtual card order gone through yet?
      - Can I see whether a queued card order cancellation is still pending?
      instructions:
      - text: Get the cancellation status of card order {order_id}.
        slots:
          order_id: path.order_id
      - text: Check whether the cancel request for virtual card order {order_id} is done.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/merchantcard/v3/orders/{order_id}/cancel-request'].post
  update:
    x-apievangelist-phrasing:
      intent: Request cancellation of a virtual card order
      effect: destructive
      questions:
      - How do I cancel an order that has a virtual card settlement?
      - Does cancelling a virtual card order happen immediately or asynchronously?
      instructions:
      - text: Request cancellation of virtual card order {order_id}.
        slots:
          order_id: path.order_id
      - text: Queue card order {order_id} for cancellation.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-10-01'