# 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 Subscriptions API
  version: 1.0.0
extends: openapi/optimizely-subscriptions-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/Subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List product subscriptions
      effect: read
      questions:
      - Which customers have recurring product subscriptions set up?
      - Can I filter subscriptions by customer or website?
      instructions:
      - text: List all subscriptions.
      - text: Show subscriptions matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a recurring product subscription
      effect: write
      questions:
      - How do I set up a monthly repeat order for a customer?
      - Can a subscription only ship in certain months of the year?
      instructions:
      - text: Create a subscription for customer {customerId} on product {productId} every {cyclePeriod}.
        slots:
          customerId: requestBody.customerId
          productId: requestBody.productId
          cyclePeriod: requestBody.cyclePeriod
      - text: Set up a {cyclePeriod} subscription that runs {totalCycles} cycles starting {activateOn}.
        slots:
          cyclePeriod: requestBody.cyclePeriod
          totalCycles: requestBody.totalCycles
          activateOn: requestBody.activateOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Subscriptions({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subscription
      effect: read
      questions:
      - What cycle and ship-to does a given subscription use?
      - Can I look up one subscription by its ID?
      instructions:
      - text: Get subscription {id}.
        slots:
          id: path.id
      - text: Show the schedule for subscription {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Subscriptions({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a subscription entirely
      effect: write
      questions:
      - How do I overwrite every field on a subscription record?
      - Can I fully replace a subscription's settings in one request?
      instructions:
      - text: Replace subscription {id} with cycle period {cyclePeriod}.
        slots:
          id: path.id
          cyclePeriod: requestBody.cyclePeriod
      - text: Overwrite all fields of subscription {id}, cycle {cyclePeriod}, {periodsPerCycle} periods per cycle.
        slots:
          id: path.id
          cyclePeriod: requestBody.cyclePeriod
          periodsPerCycle: requestBody.periodsPerCycle
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Subscriptions({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a subscription
      effect: destructive
      questions:
      - How do I permanently remove one subscription?
      - Does deleting a subscription support an If-Match concurrency check?
      instructions:
      - text: Delete subscription {id}.
        slots:
          id: path.id
      - text: Remove subscription {id} if its ETag is {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Subscriptions({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update some fields of a subscription
      effect: write
      questions:
      - How do I change when a subscription deactivates?
      - Can I switch a subscription to a different ship-to without resending everything?
      instructions:
      - text: Set deactivate date {deactivateOn} on subscription {id}, cycle {cyclePeriod}.
        slots:
          id: path.id
          deactivateOn: requestBody.deactivateOn
          cyclePeriod: requestBody.cyclePeriod
      - text: Change ship-to on subscription {id} to {shipToId} keeping cycle {cyclePeriod}.
        slots:
          id: path.id
          shipToId: requestBody.shipToId
          cyclePeriod: requestBody.cyclePeriod
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Subscriptions/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new subscription
      effect: read
      questions:
      - What defaults does a new subscription start with?
      - Is there a blank subscription template to fill in?
      instructions:
      - text: Get the default field values for a new subscription.
      - text: Show a blank subscription record.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Subscriptions/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive subscriptions via the archive action
      effect: write
      questions:
      - How do I archive subscriptions using the POST archive action?
      - Can I archive several subscriptions without deleting them?
      instructions:
      - text: Archive subscriptions {ids} with the archive action.
        slots:
          ids: query.ids
      - text: Run the POST archive action on subscriptions {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/subscriptions/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive subscriptions via the DELETE route
      effect: destructive
      questions:
      - Is there a DELETE archive endpoint for subscriptions?
      - Which route archives subscriptions using the DELETE method?
      instructions:
      - text: Archive subscriptions {ids} through the DELETE archive route.
        slots:
          ids: query.ids
      - text: Call DELETE subscriptions/archive for {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/subscriptions/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several subscriptions
      effect: destructive
      questions:
      - How do I bulk delete a list of subscriptions permanently?
      - Can I delete many subscriptions in one request?
      instructions:
      - text: Bulk delete subscriptions {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every subscription in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/subscriptions({key})/customerorders({customerorderKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order generated by a subscription
      effect: read
      questions:
      - Which orders has a subscription generated?
      - Can I look up a specific order linked to a subscription?
      instructions:
      - text: Get order {customerorderKey} from subscription {key}.
        slots:
          key: path.key
          customerorderKey: path.customerorderKey
      - text: Show customer order {customerorderKey} linked to subscription {key}.
        slots:
          key: path.key
          customerorderKey: path.customerorderKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/subscriptions({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a subscription
      effect: read
      questions:
      - How do I read a custom property on a subscription?
      - Can I fetch one custom field value from a subscription?
      instructions:
      - text: Get custom property {custompropertyKey} of subscription {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show the {custompropertyKey} custom property on subscription {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/subscriptions({key})/subscriptionlines({subscriptionlineKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a line item on a subscription
      effect: read
      questions:
      - What products and quantities are on a subscription's lines?
      - Can I look up one line of a subscription?
      instructions:
      - text: Get line {subscriptionlineKey} of subscription {key}.
        slots:
          key: path.key
          subscriptionlineKey: path.subscriptionlineKey
      - text: Show subscription line {subscriptionlineKey} on subscription {key}.
        slots:
          key: path.key
          subscriptionlineKey: path.subscriptionlineKey
      method: generated
      generated: '2026-09-26'