API Evangelist conversational phrasing for Admin API V1 Gift Cards 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 Gift Cards API
  version: 1.0.0
extends: openapi/optimizely-gift-cards-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: 13
- target: $.paths['/api/v1/admin/GiftCards'].get
  update:
    x-apievangelist-phrasing:
      intent: List gift cards
      effect: read
      questions:
      - Which gift cards have been issued in Optimizely Commerce?
      - Can I filter gift cards to only active ones that haven't expired?
      instructions:
      - text: List all gift cards.
      - text: Show gift cards matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GiftCards'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a new gift card
      effect: write
      questions:
      - What details are required to issue a gift card to someone?
      - Can I set an amount and expiry date when creating a gift card?
      instructions:
      - text: Issue gift card {giftCardNumber} with PIN {pin} to {firstName} {lastName} at {email}.
        slots:
          giftCardNumber: requestBody.giftCardNumber
          pin: requestBody.pin
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
      - text: Create a {giftCardType} gift card worth {amount} expiring {expiresOn}.
        slots:
          giftCardType: requestBody.giftCardType
          amount: requestBody.amount
          expiresOn: requestBody.expiresOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GiftCards({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one gift card
      effect: read
      questions:
      - What is the balance and expiry of a specific gift card?
      - Can I pull up one gift card record by its id?
      instructions:
      - text: Fetch gift card {id}.
        slots:
          id: path.id
      - text: Show the amount and recipient of gift card {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GiftCards({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a gift card record
      effect: write
      questions:
      - Can I overwrite a whole gift card record at once?
      - Does replacing a gift card require resending its number, PIN and recipient?
      instructions:
      - text: Replace gift card {id} with number {giftCardNumber} and PIN {pin}.
        slots:
          id: path.id
          giftCardNumber: requestBody.giftCardNumber
          pin: requestBody.pin
      - text: Overwrite the full record of gift card {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GiftCards({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one gift card
      effect: destructive
      questions:
      - How do I remove a single gift card record?
      - Can deleting a gift card be conditional on its ETag?
      instructions:
      - text: Delete gift card {id}.
        slots:
          id: path.id
      - text: Delete gift card {id} only if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GiftCards({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update part of a gift card
      effect: write
      questions:
      - Can I deactivate a gift card without deleting it?
      - Is it possible to extend just the expiry date of a gift card?
      instructions:
      - text: Set gift card {id} active flag to {isActive}.
        slots:
          id: path.id
          isActive: requestBody.isActive
      - text: Extend gift card {id} to expire on {expiresOn}.
        slots:
          id: path.id
          expiresOn: requestBody.expiresOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GiftCards/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new gift card
      effect: read
      questions:
      - What defaults does a new gift card record start with?
      - Is there a blank gift card template to fill in?
      instructions:
      - text: Get the default field values for a new gift card.
      - text: Show the empty gift card template.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GiftCards/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive gift cards via the OData archive action
      effect: destructive
      questions:
      - Can I retire gift cards with the OData Default.archive action?
      - What does calling the gift card archive action do to the cards I pass?
      instructions:
      - text: Run the OData archive action on gift cards {ids}.
        slots:
          ids: query.ids
      - text: Archive gift cards {ids} with Default.archive.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/giftcards/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive gift cards through the archive route
      effect: destructive
      questions:
      - Is there a REST route for archiving a batch of gift cards?
      - What does a DELETE on giftcards/archive do?
      instructions:
      - text: Archive gift cards {ids} using the giftcards/archive route.
        slots:
          ids: query.ids
      - text: Send the batch archive request for gift cards {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/giftcards/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete several gift cards
      effect: destructive
      questions:
      - Can I bulk delete a list of gift cards?
      - Is there a way to permanently remove many gift cards in one request?
      instructions:
      - text: Bulk delete gift cards {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every gift card in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/giftcards({key})/customerorders({customerorderKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order a gift card was used on
      effect: read
      questions:
      - Which customer orders has a gift card been applied to?
      - Can I read one order linked to a gift card?
      instructions:
      - text: Get order {customerorderKey} linked to gift card {key}.
        slots:
          key: path.key
          customerorderKey: path.customerorderKey
      - text: Show customer order {customerorderKey} that used gift card {key}.
        slots:
          key: path.key
          customerorderKey: path.customerorderKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/giftcards({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a gift card
      effect: read
      questions:
      - How can I read a custom property stored on a gift card?
      - Can I fetch one custom field value from a gift card record?
      instructions:
      - text: Get custom property {custompropertyKey} of gift card {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show the {custompropertyKey} custom property on gift card {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/giftcards({key})/giftcardtransactions({giftcardtransactionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a transaction on a gift card
      effect: read
      questions:
      - Where can I see a redemption or top-up transaction on a gift card?
      - Can I look up one gift card transaction by key?
      instructions:
      - text: Get transaction {giftcardtransactionKey} of gift card {key}.
        slots:
          key: path.key
          giftcardtransactionKey: path.giftcardtransactionKey
      - text: Show gift card transaction {giftcardtransactionKey} for card {key}.
        slots:
          key: path.key
          giftcardtransactionKey: path.giftcardtransactionKey
      method: generated
      generated: '2026-09-26'