Update or cancel a subscription

Send `{ "status": "cancelled" }` to cancel now, or `{ "cancel_at_period_end": true }` to let the paid period run out without renewing. `metadata` is the only other thing this endpoint changes, and it replaces what was stored. What a subscription charges — its product, amount, currency, interval, quantity and customer — is fixed when it starts: to change any of it, cancel this subscription and take a new checkout. Cancelling cannot be taken back. A subscription the card processor renews is stopped there first, and if the processor does not confirm, nothing changes here and the answer is `502 CANCELLATION_FAILED`. For such a subscription, ending it at the end of the period stops those renewals immediately (the period is paid already), so it cannot be resumed: `cancel_at_period_end: false` afterwards answers `409 CANCELLATION_FINAL`. Changing an already cancelled subscription answers `409 SUBSCRIPTION_CANCELLED`, and a renewal being charged right now answers `409 CHARGE_IN_PROGRESS` — try again in a minute.

curl -X PATCH "https://example.com/subscriptions/sub_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c" \  -H "Content-Type: application/json" \  -d '{    "status": "cancelled"  }'

{  "object": "subscription",  "subscription_id": "sub_4e8f1a6b2c7d3e9f0a5b1c6d2e7f3a8b",  "status": "cancelled",  "product_id": "pdt_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",  "name": "Pro plan",  "quantity": 1,  "recurring_amount": 9900,  "currency": "AED",  "billing_interval": "month",  "interval_count": 1,  "customer": {    "customer_id": "cus_2c4e6a8b0d1f4a3c5e7b9d1f3a5c7e9b",    "name": "Nour Al Abbas",    "email": "nour.alabbas@example.com"  },  "payment_method": {    "brand": "visa",    "last4": "4242",    "exp_month": 4,    "exp_year": 2029  },  "current_period_start": "2026-09-01T10:00:00.000Z",  "next_billing_date": "2026-10-01T10:00:00.000Z",  "cancel_at_period_end": false,  "cancelled_at": "2026-09-20T12:00:00.000Z",  "cancellation_reason": "requested",  "failed_payment_attempts": 0,  "next_retry_at": null,  "checkout_session_id": "cks_1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c",  "metadata": {},  "livemode": true,  "created_at": "2026-08-01T10:00:00.000Z"}