`StripeSubscriptionManager`

\Benecaster\Payment\StripeSubscriptionManager

Class Premium

Thin wrapper over the Stripe Subscriptions and Billing Portal APIs. Does not persist Benecaster subscription records, manage feed tokens, or fire Benecaster action hooks — all orchestration lives above this class, in NativeBridge and the Stripe webhook handling that raises benecaster_stripe_membership_subscription_*. Add-ons should react to Benecaster lifecycle actions rather than calling the Stripe API directly via this class. Every \Stripe\Subscription and \Stripe\Invoice it returns is in Stripe’s 2025-08-27.basil layout (Payment\StripeClient::API_VERSION): no top-level current_period_start or current_period_end (they are on each item), no invoice.payment_intent, charge or subscription (use parent.subscription_details.subscription and the invoice’s payments list), and tax in total_taxes. Reading $sub->current_period_end off create_subscription()‘s result gives null. Use Membership\StripePayloadShape for reads that work in both layouts.

Methods

Method	Visibility	Since	Description
`create_subscription( int $show_id, string $customer_id, string $price_id, array $params = [], ?string $idempotency_key = null ): \Stripe\Subscription`	Public	—	Creates a new Stripe subscription. Derive the idempotency key from show_id, customer_id, and price_id to make retries safe against duplicate charges.
`retrieve_subscription( int $show_id, string $subscription_id ): \Stripe\Subscription`	Public	—	Fetches the live Stripe Subscription object. `PriceChangeApplier` uses it to read `current_period_end` on each apply pass, since a subscriber is only moved once that has reached the renewal named in their notice.
`cancel_subscription( int $show_id, string $subscription_id, bool $at_period_end = true ): \Stripe\Subscription`	Public	—	Cancels a Stripe subscription. Defaults to cancel_at_period_end = true so the subscriber retains access through the current billing period.
`update_subscription( int $show_id, string $subscription_id, array $params, ?string $idempotency_key = null ): \Stripe\Subscription`	Public	—	Updates a subscription. Used for tier switches and billing-period changes. Stripe handles proration automatically per the account's proration settings.
`create_billing_portal_session( int $show_id, string $customer_id, string $return_url ): \Stripe\BillingPortal\Session`	Public	—	Creates a Stripe Billing Portal session for self-service subscription management. The subscriber is redirected to the Stripe-hosted portal and back to $return_url when done.
`list_invoices( int $show_id, string $customer_id, int $limit = 24 ): \Stripe\Collection`	Public	—	Returns the subscriber's invoice list from Stripe. $limit is clamped to [1, 100].
`create_setup_intent( int $show_id, string $customer_id ): \Stripe\SetupIntent`	Public	—	Creates an off-session SetupIntent scoped to card payment methods. Used to mount a Stripe Elements PaymentElement for payment method updates.
`attach_payment_method( int $show_id, string $customer_id, string $payment_method_id ): void`	Public	—	Attaches a PaymentMethod to the customer and sets it as invoice_settings.default_payment_method. Always call alongside set_subscription_default_payment_method() to update both layers.
`set_subscription_default_payment_method( int $show_id, string $subscription_id, string $payment_method_id ): \Stripe\Subscription`	Public	—	Pins a PaymentMethod to the subscription so the next renewal uses it without falling back to the customer default.
`retrieve_payment_method( int $show_id, string $payment_method_id ): \Stripe\PaymentMethod`	Public	—	Retrieves a PaymentMethod object (brand, last4, expiry). Used to populate the billing portal UI.
`retrieve_customer( int $show_id, string $customer_id ): \Stripe\Customer`	Public	—	Retrieves a Stripe Customer object. Used when the portal needs to read the customer's current default payment method.
`schedule_price_switch( int $show_id, string $subscription_id, string $new_price_id, array $carry_price_ids = [] ): \Stripe\SubscriptionSchedule`	Public	—	Builds a Stripe Subscription Schedule that moves the subscription to `$new_price_id` at the end of the current period, rather than updating the subscription directly (which would reset the billing anchor and invoice immediately on an interval change). `$carry_price_ids` are the Stripe Prices of the buy-ups that move with the subscriber, including free ones gained. Anything left out of the schedule's second phase is dropped at the phase change, with no warning from Stripe. That is why the parameter exists, and why an item added to the subscription after the schedule is built would be lost. Benecaster calls it when a subscriber schedules a plan change from their account page.
`release_schedule( int $show_id, string $schedule_id ): \Stripe\SubscriptionSchedule`	Public	—	Releases a Subscription Schedule, returning the subscription to normal (non-schedule-managed) billing. Called both when a pending cadence switch is cancelled or dropped, and once a switch has landed.

Name	Set by	What it does	Kept for
`wordpress_logged_in_*`	Benecaster	Keeps you signed in to your Benecaster account.	Until you sign out, or two weeks with "Remember Me".
`wordpress_sec_*`	Benecaster	Secures your signed-in session over HTTPS.	Until you sign out, or two weeks with "Remember Me".
`wp-settings-*`	Benecaster	Remembers your admin screen preferences.	One year.
`benecaster_ls_purchase_sign_in`	Benecaster	Signs you in to your new account on the page you bought from, once your purchase has gone through.	Thirty minutes, or until you are signed in.
`benecaster_ls_cookie_consent`	Benecaster	Remembers the choice you make on this banner, so we do not ask again.	One year.

Name	Set by	What it does	Kept for
`__stripe_mid`	Stripe	Lets Stripe recognise the device across payment attempts to detect card fraud.	One year.
`__stripe_sid`	Stripe	The same fraud check, for the current visit only.	Thirty minutes.