API Evangelist conversational phrasing for Square Subscriptions API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Subscriptions API
  version: 1.0.0
extends: openapi/square-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: 12
- target: $.paths['/v2/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Enroll a customer in a subscription
      effect: write
      questions:
      - How do I sign a customer up for a subscription plan?
      - What happens if I create a subscription without a card on file?
      - Can I override the plan price for one subscriber?
      instructions:
      - text: Subscribe customer {customer_id} to plan variation {plan_variation_id} at location {location_id}.
        slots:
          customer_id: requestBody.customer_id
          plan_variation_id: requestBody.plan_variation_id
          location_id: requestBody.location_id
      - text: Enroll customer {customer_id} at {location_id} and charge card {card_id}.
        slots:
          customer_id: requestBody.customer_id
          location_id: requestBody.location_id
          card_id: requestBody.card_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/bulk-swap-plan'].post
  update:
    x-apievangelist-phrasing:
      intent: Move all subscribers to a new plan variation
      effect: write
      questions:
      - Can I migrate every active subscriber from one plan variation to another?
      - Is there a bulk way to swap plans for all subscriptions at a location?
      instructions:
      - text: Swap all subscriptions on {old_plan_variation_id} to {new_plan_variation_id} at location {location_id}.
        slots:
          old_plan_variation_id: requestBody.old_plan_variation_id
          new_plan_variation_id: requestBody.new_plan_variation_id
          location_id: requestBody.location_id
      - text: Bulk move subscribers at {location_id} off plan variation {old_plan_variation_id} onto {new_plan_variation_id}.
        slots:
          location_id: requestBody.location_id
          old_plan_variation_id: requestBody.old_plan_variation_id
          new_plan_variation_id: requestBody.new_plan_variation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search subscriptions by customer or location
      effect: read
      questions:
      - Which subscriptions does a given customer have?
      - Can I list subscriptions at specific locations, oldest first?
      instructions:
      - text: Search subscriptions matching {query}.
        slots:
          query: requestBody.query
      - text: Find subscriptions for the filters in {query}, up to {limit}.
        slots:
          query: requestBody.query
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one subscription
      effect: read
      questions:
      - What is the status and next billing date of a subscription?
      - Can I include scheduled actions when fetching a subscription?
      instructions:
      - text: Get subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      - text: Show subscription {subscription_id} including {include}.
        slots:
          subscription_id: path.subscription_id
          include: query.include
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update subscription fields
      effect: write
      questions:
      - Can I change the tax percentage or price override on an existing subscription?
      - How do I clear a field on a subscription?
      instructions:
      - text: Update subscription {subscription_id} with {subscription}.
        slots:
          subscription_id: path.subscription_id
          subscription: requestBody.subscription
      - text: Change the fields on subscription {subscription_id} as given in {subscription}.
        slots:
          subscription_id: path.subscription_id
          subscription: requestBody.subscription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}/actions/{action_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a scheduled subscription action
      effect: destructive
      questions:
      - Can I undo a scheduled pause or cancellation on a subscription?
      - How do I remove a pending action that is queued on a subscription?
      instructions:
      - text: Delete action {action_id} on subscription {subscription_id}.
        slots:
          action_id: path.action_id
          subscription_id: path.subscription_id
      - text: Remove the scheduled action {action_id} from subscription {subscription_id}.
        slots:
          action_id: path.action_id
          subscription_id: path.subscription_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}/billing-anchor'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a subscription's billing day
      effect: write
      questions:
      - Can I move the day of the month a subscriber is billed?
      - When does a billing anchor date change take effect?
      instructions:
      - text: Change subscription {subscription_id} to bill on day {monthly_billing_anchor_date}.
        slots:
          subscription_id: path.subscription_id
          monthly_billing_anchor_date: requestBody.monthly_billing_anchor_date
      - text: Set billing anchor for {subscription_id} to {monthly_billing_anchor_date} starting {effective_date}.
        slots:
          subscription_id: path.subscription_id
          monthly_billing_anchor_date: requestBody.monthly_billing_anchor_date
          effective_date: requestBody.effective_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a subscription
      effect: destructive
      questions:
      - How do I cancel a customer's subscription at the end of the billing period?
      - Does canceling a subscription stop billing immediately?
      instructions:
      - text: Cancel subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      - text: Schedule cancellation of subscription {subscription_id} at period end.
        slots:
          subscription_id: path.subscription_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List events for a subscription
      effect: read
      questions:
      - What changes have happened to a subscription over time?
      - Can I see when a subscription was paused, resumed or swapped?
      instructions:
      - text: List events for subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      - text: Show the history of subscription {subscription_id}, {limit} events at a time.
        slots:
          subscription_id: path.subscription_id
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}/pause'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause a subscription
      effect: write
      questions:
      - Can a subscriber pause for a couple of billing cycles?
      - How do I pause a subscription and set when it resumes?
      instructions:
      - text: Pause subscription {subscription_id} starting {pause_effective_date}.
        slots:
          subscription_id: path.subscription_id
          pause_effective_date: requestBody.pause_effective_date
      - text: Pause subscription {subscription_id} for {pause_cycle_duration} cycles because {pause_reason}.
        slots:
          subscription_id: path.subscription_id
          pause_cycle_duration: requestBody.pause_cycle_duration
          pause_reason: requestBody.pause_reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}/resume'].post
  update:
    x-apievangelist-phrasing:
      intent: Resume a paused subscription
      effect: write
      questions:
      - How do I restart a paused or deactivated subscription?
      - Can I choose whether a resume happens now or at the next billing date?
      instructions:
      - text: Resume subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      - text: Resume subscription {subscription_id} on {resume_effective_date}.
        slots:
          subscription_id: path.subscription_id
          resume_effective_date: requestBody.resume_effective_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/subscriptions/{subscription_id}/swap-plan'].post
  update:
    x-apievangelist-phrasing:
      intent: Swap one subscription to another plan
      effect: write
      questions:
      - Can I upgrade a single subscriber to a different plan variation?
      - What does swapping the plan on one subscription change?
      instructions:
      - text: Swap subscription {subscription_id} to plan variation {new_plan_variation_id}.
        slots:
          subscription_id: path.subscription_id
          new_plan_variation_id: requestBody.new_plan_variation_id
      - text: Move just subscription {subscription_id} onto plan {new_plan_variation_id}.
        slots:
          subscription_id: path.subscription_id
          new_plan_variation_id: requestBody.new_plan_variation_id
      method: generated
      generated: '2026-09-26'