Describe the bug

When retrieving a customer via $stripe->customers->retrieve($id), Stripe returns a stub {id, deleted: true} object if the customer was deleted — this is documented API behavior.

However, the SDK's Stripe\Customer class does not declare $deleted as a @property, which forces consumers using PHPStan/Psalm to add @phpstan-ignore property.notFound around the check:

$customer = $stripe->customers->retrieve($user->stripe_id);

/** @phpstan-ignore property.notFound */
if (isset($customer->deleted) && $customer->deleted === true) {
    // handle deleted customer — clear local reference, recreate, etc.
}

To Reproduce

1. Call $stripe->customers->retrieve(...) on a customer you deleted.
2. Static-analyze the return with PHPStan on max level.
3. Observe Access to an undefined property Stripe\Customer::$deleted.

Verified on stripe/stripe-php v17.6.0 and checked the stubs on master as of April 2026 — $deleted is still absent on Customer.

Expected behavior

Either:

1. Add @property null|bool \$deleted to Stripe\Customer (simplest, matches the existing pattern used by Apps\Secret), or

2. Model the deleted-customer response as a distinct DeletedCustomer class and reflect that in CustomerService::retrieve()'s return type (\Stripe\Customer|\Stripe\DeletedCustomer). This would be the most explicit, but it's a breaking-ish change for static analyzers that would require every consumer to narrow the union.

Option 1 is the pragmatic fix — no runtime change, just a docblock addition that accurately describes the API contract.

Context

• SDK version: v17.6.0
• Verified issue persists in latest `master` (checked April 2026)
• Related (old) issue: Testing for customer.deleted generates a PHP notice #73 — same root cause, runtime notices; static analysis equivalent hasn't been filed in the modern type-stub era
• Related (open) tracker: Better DX for new strong PHP types #1870 — broader DX-for-types umbrella

Workaround

Add a one-line `@phpstan-ignore property.notFound` above the check. Works, but every library consumer hits it on first encounter.