Error when accessing invoice.lines.data's item.subscription_item if the item is not a subscription item.

[gazalamuhamed-finn]

Describe the bug

When accessing item.subscription_item, I expect a None value but instead I get an Exception.

To Reproduce

stripe_invoice = stripe_repo.retrieve_stripe_invoice(existing_stripe_subscription.latest_invoice)
for item in stripe_invoice.lines.data:
     if item.subscription_item: # this throws an error if the item is not a subscription_item
        pass

Expected behavior

The expectation is that defaults to None if not a subscription_item.

(variable) subscription_item: ExpandableField[SubscriptionItem] | None
The subscription item that generated this line item. Left empty if the line item is not an explicit result of a subscription.

Code snippets

OS

macOS

Language version

Python 3.12.8

Library version

stripe 11.5.0

API version

2025-01-27.acacia

Additional context

No response

[jar-stripe]

Hi @gazalamuhamed-finn , thanks for the report and sorry for the issue you're having. Can you post the exception with stack trace that you are getting, and if possible steps to reproduce (including setting up the invoice)? I want to make sure I recreate as close to the conditions you are experience as possible. Thanks!

[gazalamuhamed-finn]

Hey @jar-stripe , does this help?

1. Create a pending item on a stripe customer that is "auto-billed" to the next subscription (I did this via the Dashboard).
2. Create a subscription with a monthly subscription_item.
3. Access the latest invoice from the subscription: stripe_invoice =self.stripe.Invoice.retrieve(stripe_subscription.latest_invoice)
4. It will have 2 items, one is a subscription_item and the other is the pending item from step 1.
5. When iterating through stripe_invoice.lines.data, accessing the second item.subscription_item throws this error:

Exception has occurred: AttributeError
subscription_item
KeyError: 'subscription_item'

6. Bonus bug: I get a similar error when trying to access item.invoice_item on the first item:

Exception has occurred: AttributeError
invoice_item
KeyError: 'invoice_item'

The issue is that the type annotations are incorrect/misleading.

[xavdid-stripe]

Thanks for the detailed reproduction steps! I've been able to reproduce.

On the surface, this is expected behavior on the part of the Python SDK. In the API response, the subscription_item in that nested object is missing, so the SDK (correctly) treats it as a KeyError.

The real question is if that API behavior is expected. Typically, when something is marked as a "nullable string", that means they key is always there and may be null. That doesn't seem like the runtime behavior here though.

I'll ask around internally to see what's up and help you better set expectations. Thank you for flagging!

[gazalamuhamed-finn]

@xavdid-stripe Thank you, I understand. As a quick fix, I will try using hasattr(item, "subscription_item") before accessing item.subscription_item.

[xavdid-stripe]

That should work! It also seems like if "type" == "invoiceitem" then .invoice_item exists. If type is subscription, then subscription_item exists. But checking manually will be safest.

[aergus-work]

Hello, we have the impression that this bug still persists as of version 14.4 and affects many attributes declared as optional in the SDK. We encountered it for instance for InvoiceLineItem.subscription, which is of type Optional[ExpandableField["Subscription"]].

This makes the SDK quite awkward to work with because it doesn't fulfill its own typing claims. As the failure becomes apparent only at runtime, standard static analysis tools cannot catch problematic usages and we have to bear the mental load that whenever we want to access an attribute that is optional, we have to guard that code path with a hasttr/getattr or business logic that guarantees that the attribute exists.

[xavdid-stripe]

That's correct, this is still the case unfortunately. For some APIs, it's important to make the distinction between whether a value is null or missing. If we set optional keys to None, then users wouldn't be able to distinguish when it's important.

We've been discussing other ways to represent these fields in the API, but that's a non-trivial change and there hasn't been much motion.