# 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'