Create a Square subscription with a card on file and manage the recurring billing lifecycle

Steps

1. Create or retrieve a Customer in the Square Customers API: POST /v2/customers with name and email; if the customer already exists, search by email with POST /v2/customers/search.
2. Save a card on file: POST /v2/cards with 'source_id' (a payment token generated by Square Web Payments SDK or Square In-App Payments SDK — never a raw PAN), 'customer_id', and 'billing_address'; receive a 'card_id'.
3. Create a subscription plan (Catalog object of type 'SUBSCRIPTION_PLAN') via POST /v2/catalog/object if one does not exist, defining phases with 'cadence' (MONTHLY, ANNUAL, etc.) and 'recurring_price_money'.
4. Create the subscription: POST /v2/subscriptions with 'customer_id', 'plan_variation_id', 'location_id', and 'card_id'; Square creates invoices and charges the card automatically on each billing date.
5. Monitor subscription status via webhooks: subscribe to 'subscription.updated' and 'invoice.payment_failed' events; on failed payment Square sets the subscription to 'DELINQUENT' status after configuring retry behavior.
6. To cancel, call POST /v2/subscriptions/{subscription_id}/cancel; to pause, use POST /v2/subscriptions/{subscription_id}/pause — actions take effect at the end of the current billing period unless 'immediate' is specified.