# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reference Subscriptions API
  version: 1.0.0
extends: openapi/beehiiv-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: 8
- target: $.paths['/publications/{publicationId}/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a publication's subscribers
      effect: read
      questions:
      - Who subscribes to my newsletter?
      - Can I list only premium subscribers or only active ones?
      - Can I filter subscribers by when they signed up?
      instructions:
      - text: List subscriptions on publication {publication}.
        slots:
          publication: path.publicationId
      - text: Show {status} subscribers on {publication}.
        slots:
          status: query.status
          publication: path.publicationId
      - text: List {tier} tier subscribers on publication {publication}.
        slots:
          tier: query.tier
          publication: path.publicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe a new reader
      effect: write
      questions:
      - How do I add a new subscriber to my newsletter from my signup form?
      - Can I skip the welcome email when adding a subscriber?
      - Can I record UTM source and referral code for a new signup?
      instructions:
      - text: Subscribe {email} to publication {publication}.
        slots:
          email: requestBody.email
          publication: path.publicationId
      - text: Add new subscriber {email} with UTM source {utm_source}.
        slots:
          email: requestBody.email
          utm_source: requestBody.utm_source
      - text: Subscribe {email} and enroll them in automations {automation_ids}.
        slots:
          email: requestBody.email
          automation_ids: requestBody.automation_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/subscriptions/by_email/{email}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a subscriber by email
      effect: read
      questions:
      - Is a given email address subscribed to my newsletter?
      - Do I need to URL-encode the email when looking up a subscriber?
      instructions:
      - text: Look up the subscription for {email} on publication {publication}.
        slots:
          email: path.email
          publication: path.publicationId
      - text: Check whether {email} is subscribed, including {expand}.
        slots:
          email: path.email
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/subscriptions/by_email/{email}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a subscriber found by email
      effect: write
      questions:
      - How do I change a subscriber's tier when I only know their email?
      - Can I unsubscribe someone by their email address?
      instructions:
      - text: Update the subscriber with email {email} on {publication} to tier {tier}.
        slots:
          email: path.email
          publication: path.publicationId
          tier: requestBody.tier
      - text: Unsubscribe the reader whose email is {email}.
        slots:
          email: path.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/subscriptions/{subscriptionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subscriber by subscription ID
      effect: read
      questions:
      - Can I fetch one subscriber's details by their subscription ID?
      - What replaced the old lookup by subscriber ID?
      instructions:
      - text: Get subscription {subscription} on publication {publication}.
        slots:
          subscription: path.subscriptionId
          publication: path.publicationId
      - text: Show subscriber {subscription} with {expand} expanded.
        slots:
          subscription: path.subscriptionId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/subscriptions/{subscriptionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a subscriber by ID (PUT)
      effect: write
      questions:
      - How do I PUT changes to a subscriber's tier or custom fields by subscription ID?
      - Can I use PUT to unsubscribe a subscriber by ID?
      instructions:
      - text: PUT tier {tier} on subscription {subscription} in publication {publication}.
        slots:
          tier: requestBody.tier
          subscription: path.subscriptionId
          publication: path.publicationId
      - text: Unsubscribe subscription {subscription} using the PUT update.
        slots:
          subscription: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/subscriptions/{subscriptionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a subscriber
      effect: destructive
      questions:
      - How do I permanently delete a subscriber and all their data?
      - Does deleting a premium subscriber stop their billing?
      instructions:
      - text: Permanently delete subscription {subscription} from publication {publication}.
        slots:
          subscription: path.subscriptionId
          publication: path.publicationId
      - text: Erase subscriber {subscription} and all their data for good.
        slots:
          subscription: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/subscriptions/{subscriptionId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a subscriber by ID (PATCH)
      effect: write
      questions:
      - Can I PATCH a subscriber's custom fields using their subscription ID?
      - What's the PATCH way to change one subscriber's email or Stripe customer?
      instructions:
      - text: PATCH subscription {subscription} on {publication} with custom fields {custom_fields}.
        slots:
          subscription: path.subscriptionId
          publication: path.publicationId
          custom_fields: requestBody.custom_fields
      - text: PATCH the Stripe customer on subscription {subscription} to {stripe_customer_id}.
        slots:
          subscription: path.subscriptionId
          stripe_customer_id: requestBody.stripe_customer_id
      method: generated
      generated: '2026-09-26'