API Evangelist conversational phrasing for Mirakl Offers API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mirakl Offers API
  version: 1.0.0
extends: openapi/mirakl-offers-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: 19
- target: $.paths['/api/offers/{offer}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an offer's details
      effect: read
      questions:
      - How do I look up the details of a single offer?
      - Can I see the price an offer would have for a specific channel or customer organization?
      instructions:
      - text: Get offer {offer}.
        slots:
          offer: path.offer
      - text: Show offer {offer} priced for channel {pricing_channel_code}.
        slots:
          offer: path.offer
          pricing_channel_code: query.pricing_channel_code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/{offer}/quantity'].get
  update:
    x-apievangelist-phrasing:
      intent: Get available stock for an offer
      effect: read
      questions:
      - How much stock is left on a given offer?
      - Why does an offer show a quantity of zero even though it exists?
      instructions:
      - text: Get the available quantity for offer {offer}.
        slots:
          offer: path.offer
      - text: Check whether offer {offer} still has stock.
        slots:
          offer: path.offer
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Download changed offers as CSV (deprecated)
      effect: read
      questions:
      - Can I still pull a synchronous CSV of offers changed since my last request?
      - Which offers were deleted since my last export, using the old CSV export?
      instructions:
      - text: Download the offers CSV of changes since {last_request_date}.
        slots:
          last_request_date: query.last_request_date
      - text: Export offers for channels {channel_codes} with the deprecated CSV endpoint.
        slots:
          channel_codes: query.channel_codes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/export/async'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an asynchronous offer export
      effect: read
      questions:
      - What's the recommended way to export a large offer catalogue as CSV or JSON?
      - Can I split an offer export into chunks by size or item count?
      instructions:
      - text: Start an async offer export of offers updated since {last_request_date}.
        slots:
          last_request_date: requestBody.last_request_date
      - text: Export offers as {export_type} in chunks of {items_per_chunk} items.
        slots:
          export_type: requestBody.export_type
          items_per_chunk: requestBody.items_per_chunk
      - text: Launch a full offer export including inactive offers.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/export/async/status/{tracking_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an offer export's status
      effect: read
      questions:
      - Is my asynchronous offer export finished yet?
      - Where do I get the file links once an offer export completes?
      instructions:
      - text: Check the status of offer export {tracking_id}.
        slots:
          tracking_id: path.tracking_id
      - text: Get the download URLs for completed offer export {tracking_id}.
        slots:
          tracking_id: path.tracking_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dynamic-url/The+URL+is+retrieved+from+OF53+output/OF54'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an offer export file chunk
      effect: read
      questions:
      - How do I fetch each chunk of a completed offer export?
      - Can I retrieve the actual offer file after the export is done?
      instructions:
      - text: Download the offer export chunk for {tracking_id}.
        slots:
          tracking_id: path.tracking_id
      - text: Retrieve the offer files produced by export {tracking_id}.
        slots:
          tracking_id: path.tracking_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/products/offers'].get
  update:
    x-apievangelist-phrasing:
      intent: List offers for given products
      effect: read
      questions:
      - Which sellers have offers on a given product and at what price?
      - Can I compare competing offers for a product within a shipping zone?
      - How do I get all offers for several products in one call?
      instructions:
      - text: List offers for products {product_ids}.
        slots:
          product_ids: query.product_ids
      - text: Show offers on products {product_ids} from shops {shop_ids}.
        slots:
          product_ids: query.product_ids
          shop_ids: query.shop_ids
      - text: List offers for product references {product_references} in zone {shipping_zones}.
        slots:
          product_references: query.product_references
          shipping_zones: query.shipping_zones
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/imports'].get
  update:
    x-apievangelist-phrasing:
      intent: List offer file imports
      effect: read
      questions:
      - What offer imports have I run recently and did they succeed?
      - Can I filter offer imports by status or date range?
      instructions:
      - text: List offer imports between {start_date} and {end_date}.
        slots:
          start_date: query.start_date
          end_date: query.end_date
      - text: Show offer imports with status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/imports'].post
  update:
    x-apievangelist-phrasing:
      intent: Import an offer file
      effect: write
      questions:
      - How do I bulk create, update or delete offers by uploading a file?
      - Can an offer file import also create the products?
      instructions:
      - text: Import offer file {file} in {import_mode} mode.
        slots:
          file: requestBody.file
          import_mode: requestBody.import_mode
      - text: Upload {file} to update offers for shop {shop_id} in {import_mode} mode.
        slots:
          file: requestBody.file
          shop_id: query.shop_id
          import_mode: requestBody.import_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/imports/{import}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an offer import's statistics
      effect: read
      questions:
      - How many lines of my offer import succeeded or failed?
      - What's the status of a specific offer import?
      instructions:
      - text: Get the status and statistics of offer import {import}.
        slots:
          import: path.import
      - text: Check how offer import {import} went for shop {shop_id}.
        slots:
          import: path.import
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/imports/{import}/error_report'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an offer import error report
      effect: read
      questions:
      - Where can I see which lines failed in my offer import?
      - What file format is the offer import error report returned in?
      instructions:
      - text: Download the error report for offer import {import}.
        slots:
          import: path.import
      - text: Get the failed lines of offer import {import}.
        slots:
          import: path.import
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a shop's offers
      effect: read
      questions:
      - What offers does my shop currently have?
      - Can I list only my favorite offers or those for a specific SKU?
      instructions:
      - text: List the offers of shop {shop_id}.
        slots:
          shop_id: query.shop_id
      - text: Show my offers for SKU {sku}.
        slots:
          sku: query.sku
      - text: List my offers on product {product_id}.
        slots:
          product_id: query.product_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create, update or delete offers via JSON
      effect: write
      questions:
      - How do I update offers directly with a JSON payload instead of a file?
      - Do fields I leave out get reset when I update offers?
      instructions:
      - text: Send these offers {offers} to create or update them.
        slots:
          offers: requestBody.offers
      - text: Update offers {offers} for shop {shop_id}.
        slots:
          offers: requestBody.offers
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/pricing/imports'].get
  update:
    x-apievangelist-phrasing:
      intent: List offer price imports
      effect: read
      questions:
      - Did my last price file import finish without errors?
      - Can I list price imports by status or date?
      instructions:
      - text: Get the price import {import_id}.
        slots:
          import_id: query.import_id
      - text: List price imports with status {status} since {start_date}.
        slots:
          status: query.status
          start_date: query.start_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/pricing/imports'].post
  update:
    x-apievangelist-phrasing:
      intent: Import an offer price file
      effect: write
      questions:
      - How do I upload all prices for my offers from a CSV?
      - Are existing prices I don't include in the price file deleted?
      instructions:
      - text: Import price file {file}.
        slots:
          file: requestBody.file
      - text: Upload price file {file} for shop {shop_id}.
        slots:
          file: requestBody.file
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/pricing/imports/{import_id}/error_report'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a price import error report
      effect: read
      questions:
      - Which offer prices failed in my price import and why?
      - Can I get a price error file that's ready to fix and reimport?
      instructions:
      - text: Download the error report for price import {import_id}.
        slots:
          import_id: path.import_id
      - text: Get the rejected price lines of import {import_id}.
        slots:
          import_id: path.import_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/stock/imports'].post
  update:
    x-apievangelist-phrasing:
      intent: Import an offer stock file
      effect: write
      questions:
      - How do I update stock levels for my offers from a CSV file?
      - Can I update stock per warehouse instead of globally?
      instructions:
      - text: Import stock file {file}.
        slots:
          file: requestBody.file
      - text: Upload stock file {file} for shop {shop_id}.
        slots:
          file: requestBody.file
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/stock/imports/{import_id}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a stock import's status
      effect: read
      questions:
      - Did my stock file import complete?
      - How many stock lines were processed in an import?
      instructions:
      - text: Get the status of stock import {import_id}.
        slots:
          import_id: path.import_id
      - text: Show statistics for stock import {import_id}.
        slots:
          import_id: path.import_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/stock/imports/{import_id}/error_report'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a stock import error report
      effect: read
      questions:
      - Which stock lines were rejected in my stock import?
      - Where do I get the stock errors as a CSV to fix and reupload?
      instructions:
      - text: Download the error report for stock import {import_id}.
        slots:
          import_id: path.import_id
      - text: Get the failed stock lines of import {import_id}.
        slots:
          import_id: path.import_id
      method: generated
      generated: '2026-09-26'