Retrieve the subscription using GET /subscriptions/:id to confirm its status and current external_variant_id
Look up the new variant's shopify_variant_id from the product catalog
Send PUT /subscriptions/:id with the updated shopify_variant_id, price, and any changed properties
Verify the response reflects the new variant and that next_charge_scheduled_at is unchanged
Optionally update the queue charge via POST /charges/:id/change_next_charge_date if the swap warrants a billing reset
Known gotchas
Changing the variant does not automatically update the price; you must explicitly pass the new price in the same PUT request or the old price persists
Swapping to a variant in a different selling plan group may cause the subscription to become invalid; confirm selling plan compatibility before the swap
Recharge webhooks fire a subscription/updated event but not a charge recalculation event; downstream systems must listen and re-fetch the next charge to get updated totals
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