# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Stripe Subscription Subscription Items API
  version: 1.0.0
extends: openapi/stripe-subscription-items-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: 7
- target: $.paths['/v1/subscription_items'].get
  update:
    x-apievangelist-phrasing:
      intent: List items on a subscription
      effect: read
      questions:
      - How do I see every price and quantity on a subscription?
      - Which items make up this customer's subscription?
      instructions:
      - text: List items on subscription {subscription}.
        slots:
          subscription: query.subscription
      - text: Show the first {limit} items of subscription {subscription}.
        slots:
          limit: query.limit
          subscription: query.subscription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/subscription_items'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an item to a subscription
      effect: write
      questions:
      - How do I add an add-on to an existing subscription?
      - Does adding an item change the items already on the subscription?
      - Can I control proration when adding an item?
      instructions:
      - text: Add price {price} to subscription {subscription}.
        slots:
          price: requestBody.price
          subscription: requestBody.subscription
      - text: Add {quantity} of price {price} to subscription {subscription}.
        slots:
          quantity: requestBody.quantity
          price: requestBody.price
          subscription: requestBody.subscription
      - text: Add price {price} to subscription {subscription} with proration {proration_behavior}.
        slots:
          price: requestBody.price
          subscription: requestBody.subscription
          proration_behavior: requestBody.proration_behavior
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/subscription_items/{item}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subscription item
      effect: read
      questions:
      - How do I look up one line item on a subscription?
      - What price and quantity does this subscription item have?
      instructions:
      - text: Show subscription item {item}.
        slots:
          item: path.item
      - text: Get the price and quantity of subscription item {item}.
        slots:
          item: path.item
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/subscription_items/{item}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a subscription item
      effect: write
      questions:
      - How do I change the quantity of seats on a subscription?
      - Can I swap an item to a different price mid-cycle?
      instructions:
      - text: Set the quantity of subscription item {item} to {quantity}.
        slots:
          item: path.item
          quantity: requestBody.quantity
      - text: Switch subscription item {item} to price {price}.
        slots:
          item: path.item
          price: requestBody.price
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/subscription_items/{item}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an item from a subscription
      effect: destructive
      questions:
      - How do I remove an add-on without canceling the whole subscription?
      - Can I clear recorded usage when removing a subscription item?
      instructions:
      - text: Remove subscription item {item}.
        slots:
          item: path.item
      - text: 'Remove subscription item {item} and clear its usage: {clear_usage}.'
        slots:
          item: path.item
          clear_usage: requestBody.clear_usage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/subscription_items/{subscription_item}/usage_record_summaries'].get
  update:
    x-apievangelist-phrasing:
      intent: Get usage totals for a subscription item
      effect: read
      questions:
      - How much metered usage has a subscription item recorded this period?
      - Can I see usage summarized per billing period?
      instructions:
      - text: Show usage summaries for subscription item {subscription_item}.
        slots:
          subscription_item: path.subscription_item
      - text: List the last {limit} usage periods for subscription item {subscription_item}.
        slots:
          limit: query.limit
          subscription_item: path.subscription_item
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/subscription_items/{subscription_item}/usage_records'].post
  update:
    x-apievangelist-phrasing:
      intent: Report metered usage
      effect: write
      questions:
      - How do I report usage for a metered subscription?
      - Can I overwrite a usage quantity instead of adding to it?
      instructions:
      - text: Record {quantity} units of usage on subscription item {subscription_item}.
        slots:
          quantity: requestBody.quantity
          subscription_item: path.subscription_item
      - text: Report {quantity} usage on {subscription_item} at {timestamp} with action {action}.
        slots:
          quantity: requestBody.quantity
          subscription_item: path.subscription_item
          timestamp: requestBody.timestamp
          action: requestBody.action
      method: generated
      generated: '2026-09-26'