# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Talon One Coupons API
  version: 1.0.0
extends: openapi/talon-one-coupons-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: 17
- target: $.paths['/v1/coupon_reservations/{couponValue}'].post
  update:
    x-apievangelist-phrasing:
      intent: Reserve a coupon code for specific customers
      effect: write
      questions:
      - How do I reserve a coupon code so only certain customers can use it?
      - Can one coupon be reserved for several customer profiles at once?
      instructions:
      - text: Reserve coupon {couponValue} for customers {integrationIDs}.
        slots:
          couponValue: path.couponValue
          integrationIDs: requestBody.integrationIDs
      - text: Mark coupon code {couponValue} as reserved for profile {integrationIDs}.
        slots:
          couponValue: path.couponValue
          integrationIDs: requestBody.integrationIDs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/coupon_reservations/{couponValue}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove coupon reservations from customers
      effect: destructive
      questions:
      - Can I take back a coupon I reserved for a customer?
      - What removes a coupon reservation for a list of customer profiles?
      instructions:
      - text: Remove the reservation of coupon {couponValue} for customers {integrationIDs}.
        slots:
          couponValue: path.couponValue
          integrationIDs: requestBody.integrationIDs
      - text: Unreserve coupon code {couponValue} from profile {integrationIDs}.
        slots:
          couponValue: path.couponValue
          integrationIDs: requestBody.integrationIDs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/coupon_reservations/customerprofiles/{couponValue}'].get
  update:
    x-apievangelist-phrasing:
      intent: List customers who have a coupon reserved
      effect: read
      questions:
      - Which customers currently hold a reservation on a given coupon code?
      - Does the reserved-customer list include both hard and soft reservations?
      instructions:
      - text: List the customers who have coupon {couponValue} reserved.
        slots:
          couponValue: path.couponValue
      - text: Show who reserved coupon code {couponValue}.
        slots:
          couponValue: path.couponValue
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons'].put
  update:
    x-apievangelist-phrasing:
      intent: Bulk update all or a batch of a campaign's coupons
      effect: write
      questions:
      - Can I extend the expiry date of every coupon in a campaign at once?
      - How do I change the usage limit for one batch of coupons?
      instructions:
      - text: Set the expiry date of all coupons in campaign {campaignId} of application {applicationId} to {expiryDate}.
        slots:
          campaignId: path.campaignId
          applicationId: path.applicationId
          expiryDate: requestBody.expiryDate
      - text: Change the usage limit to {usageLimit} for coupon batch {batchID} in campaign {campaignId}, application {applicationId}.
        slots:
          usageLimit: requestBody.usageLimit
          batchID: requestBody.batchID
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate coupon codes from a pattern
      effect: write
      questions:
      - How many coupons can I generate in one go, with and without a unique prefix?
      - Can I generate coupon codes that follow a specific pattern for a campaign?
      - What's the way to create a single coupon for one recipient?
      instructions:
      - text: Create {numberOfCoupons} coupons in campaign {campaignId} of application {applicationId}.
        slots:
          numberOfCoupons: requestBody.numberOfCoupons
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Generate {numberOfCoupons} coupons with prefix {uniquePrefix} for campaign {campaignId} in application {applicationId}.
        slots:
          numberOfCoupons: requestBody.numberOfCoupons
          uniquePrefix: requestBody.uniquePrefix
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Create {numberOfCoupons} coupon for customer {recipientIntegrationId} in campaign {campaignId}, application {applicationId}.
        slots:
          numberOfCoupons: requestBody.numberOfCoupons
          recipientIntegrationId: requestBody.recipientIntegrationId
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all coupons matching filters
      effect: destructive
      questions:
      - Can I delete every expired coupon in a campaign right away?
      - How do I wipe all coupons from one batch?
      instructions:
      - text: Delete all coupons in campaign {campaignId} of application {applicationId} that expired before {expiresBefore}.
        slots:
          campaignId: path.campaignId
          applicationId: path.applicationId
          expiresBefore: query.expiresBefore
      - text: Bulk delete every coupon in batch {batchId} of campaign {campaignId}, application {applicationId}.
        slots:
          batchId: query.batchId
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons_with_recipients'].post
  update:
    x-apievangelist-phrasing:
      intent: Create coupons for a list of recipients
      effect: write
      questions:
      - Can I issue a personal coupon to each of up to 1000 customers in one call?
      - What's the limit on recipients when creating coupons for many customers?
      instructions:
      - text: Create a coupon for each of customers {recipientsIntegrationIds} in campaign {campaignId}, application {applicationId}.
        slots:
          recipientsIntegrationIds: requestBody.recipientsIntegrationIds
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Issue per-recipient coupons expiring {expiryDate} to {recipientsIntegrationIds} for campaign {campaignId} in application {applicationId}.
        slots:
          expiryDate: requestBody.expiryDate
          recipientsIntegrationIds: requestBody.recipientsIntegrationIds
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons_async'].post
  update:
    x-apievangelist-phrasing:
      intent: Create millions of coupons as a background job
      effect: write
      questions:
      - What should I use when I need more than 20,000 coupons?
      - Will I be notified when a large asynchronous coupon generation finishes?
      instructions:
      - text: Asynchronously create {numberOfCoupons} coupons with attributes {attributes} in campaign {campaignId}, application {applicationId}.
        slots:
          numberOfCoupons: requestBody.numberOfCoupons
          attributes: requestBody.attributes
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Start a background job generating {numberOfCoupons} coupons for campaign {campaignId} in application {applicationId}, with attributes {attributes}.
        slots:
          numberOfCoupons: requestBody.numberOfCoupons
          campaignId: path.campaignId
          applicationId: path.applicationId
          attributes: requestBody.attributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons_deletion_jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete coupons in a background job
      effect: destructive
      questions:
      - Can I delete a huge number of coupons asynchronously instead of in one request?
      - What filters does a coupon deletion job accept?
      instructions:
      - text: Start a coupon deletion job with filters {filters} for campaign {campaignId} in application {applicationId}.
        slots:
          filters: requestBody.filters
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Queue asynchronous deletion of coupons matching {filters} in campaign {campaignId}, application {applicationId}.
        slots:
          filters: requestBody.filters
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons/no_total'].get
  update:
    x-apievangelist-phrasing:
      intent: List a campaign's coupons
      effect: read
      questions:
      - Which coupons in my campaign have already been redeemed?
      - Can I list only the coupon codes that are still usable in a campaign?
      - How do I find the coupons issued to a particular recipient?
      instructions:
      - text: List the coupons in campaign {campaignId} of application {applicationId}.
        slots:
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Show redeemed coupons in campaign {campaignId}, application {applicationId}, where redeemed is {redeemed}.
        slots:
          campaignId: path.campaignId
          applicationId: path.applicationId
          redeemed: query.redeemed
      - text: List coupons issued to {recipientIntegrationId} in campaign {campaignId} of application {applicationId}.
        slots:
          recipientIntegrationId: query.recipientIntegrationId
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a single coupon
      effect: write
      questions:
      - Can I change the expiry date on just one coupon?
      - Why did a coupon's start date become null after I updated it?
      instructions:
      - text: Set coupon {couponId} in campaign {campaignId}, application {applicationId}, to expire on {expiryDate}.
        slots:
          couponId: path.couponId
          campaignId: path.campaignId
          applicationId: path.applicationId
          expiryDate: requestBody.expiryDate
      - text: Assign coupon {couponId} in campaign {campaignId} of application {applicationId} to recipient {recipientIntegrationId}.
        slots:
          couponId: path.couponId
          campaignId: path.campaignId
          applicationId: path.applicationId
          recipientIntegrationId: requestBody.recipientIntegrationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single coupon
      effect: destructive
      questions:
      - How do I remove one specific coupon from a campaign?
      - Can I delete an individual coupon by its ID?
      instructions:
      - text: Delete only the coupon with ID {couponId} (campaign {campaignId}, application {applicationId}).
        slots:
          couponId: path.couponId
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Remove the single coupon {couponId} in campaign {campaignId}, application {applicationId}.
        slots:
          couponId: path.couponId
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search_advanced/no_total'].post
  update:
    x-apievangelist-phrasing:
      intent: Search a campaign's coupons by attributes
      effect: read
      questions:
      - Can I find coupons in one campaign whose custom attributes match certain values?
      - Does an attribute search within a campaign match coupons that have extra attributes?
      instructions:
      - text: Search coupons in campaign {campaignId} of application {applicationId} by custom attributes.
        slots:
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Find valid coupons matching given attributes in campaign {campaignId}, application {applicationId}, where valid is {valid}.
        slots:
          campaignId: path.campaignId
          applicationId: path.applicationId
          valid: query.valid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/coupons_search_advanced/no_total'].post
  update:
    x-apievangelist-phrasing:
      intent: Search coupons by attributes across all campaigns
      effect: read
      questions:
      - Can I search coupon attributes across every campaign in an Application?
      - Is it possible to limit an application-wide coupon search to campaigns in a certain state?
      instructions:
      - text: Search coupons by attributes across all campaigns of application {applicationId}.
        slots:
          applicationId: path.applicationId
      - text: Find coupons matching given attributes in application {applicationId}, only in {campaignState} campaigns.
        slots:
          applicationId: path.applicationId
          campaignState: query.campaignState
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/import_coupons'].post
  update:
    x-apievangelist-phrasing:
      intent: Import coupons from a CSV file
      effect: write
      questions:
      - How do I upload my own coupon codes from a spreadsheet?
      - What columns does the coupon import CSV need?
      - Can duplicate codes be skipped during a coupon import?
      instructions:
      - text: Import coupons from file {upFile} into campaign {campaignId} of application {applicationId}.
        slots:
          upFile: requestBody.upFile
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Upload coupon CSV {upFile} to campaign {campaignId}, application {applicationId}, with skipDuplicates {skipDuplicates}.
        slots:
          upFile: requestBody.upFile
          campaignId: path.campaignId
          applicationId: path.applicationId
          skipDuplicates: query.skipDuplicates
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/export_coupons'].get
  update:
    x-apievangelist-phrasing:
      intent: Export coupons to a CSV file
      effect: read
      questions:
      - How can I download all coupons of an Application as a CSV?
      - Can the coupon export include coupons deleted within a date range?
      instructions:
      - text: Export the coupons of application {applicationId} to CSV.
        slots:
          applicationId: path.applicationId
      - text: Download a CSV of coupons for campaign {campaignId} in application {applicationId}.
        slots:
          campaignId: query.campaignId
          applicationId: path.applicationId
      - text: Export coupons of application {applicationId} deleted after {deletedAfter}.
        slots:
          applicationId: path.applicationId
          deletedAfter: query.deletedAfter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/coupon_rejections'].get
  update:
    x-apievangelist-phrasing:
      intent: Explain why coupons failed to redeem in a session
      effect: read
      questions:
      - Why was a customer's coupon rejected at checkout?
      - Can I get the failure reasons for one coupon code in a session, in another language?
      instructions:
      - text: Summarize coupon redemption failures in session {sessionIntegrationId}.
        slots:
          sessionIntegrationId: query.sessionIntegrationId
      - text: Explain why coupon {couponCode} was rejected in session {sessionIntegrationId}.
        slots:
          couponCode: query.couponCode
          sessionIntegrationId: query.sessionIntegrationId
      method: generated
      generated: '2026-09-26'