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.
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'.
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'.
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.
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.
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.
Known gotchas
Square subscriptions require a 'location_id' — each Square merchant may have multiple locations, and subscriptions are scoped to a location; using the wrong location ID causes permission errors or incorrect tax handling.
Payment tokens from the Square SDK expire quickly (within minutes) and are single-use; do not store them as a substitute for a saved card_id — always complete the POST /v2/cards call immediately after tokenization while the token is valid.
Square's subscription invoicing is asynchronous — after creating a subscription, the first invoice may not be immediately visible; do not poll immediately, but instead rely on webhooks for invoice and payment state changes.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp