Consumer Update Subscription

PUT /api/v2/consumer_portal/profile/subscription/:subscription_id

Consumer-only subscription update flow (items/quantities only).

This endpoint is intentionally stricter than merchant update:

accepts only items (no description, coupons, interval, cancellation, or payment-method overrides)
rejects the update if the subscription currently has subscription-level coupons
preserves existing item-level coupons for items that stay, and drops them when the item is removed/switched out
applies add-on/switch/quantity validation via consumer_profile feature flags

Execution is all-or-none:

if payment is required, neither the live subscription nor pending change is mutated yet; response is status=payment_required with payment_request and a plan preview (what is immediate after payment vs what remains scheduled)
after successful payment reconciliation (redirect/webhook), immediate + deferred targets are applied idempotently
if no payment is required, the update is applied immediately/scheduled per rules and response is status=update_scheduled with the updated subscription payload

Billing-cycle rules:

same-cycle switch + add-on addition can require immediate proration for add-ons while keeping the product switch scheduled
cross-cycle switch (e.g. monthly -> yearly) with compatible target items is fully scheduled (no immediate payment)
incompatible target cycle mixes are rejected

Request

Successful Response