Issues with invoice creation API

[EML]

I'm writing code to manually create invoices for one-off items (items which are not a 'Product'; they just have a description and a variable cost). Example Python code below. This works well, but I'm having some problems:

1. The dashboard payments page shows the description as 'Payment for invoice', which isn't helpful - you have to explicitly find and click into the open invoice to find out what it's for. What sets the 'Payment for invoice' text, and can I modify it from the API? This is not the invoice 'description' field, which only goes into the invoice 'Memo'. What I really need to do is set the description for the corresponding PaymentIntent.
2. I need some positive feedback from the API that Stripe has accepted the invoice and has, or will, attempt to email it to the customer. However, the invoice status doesn't work for this. It always shows the status as 'Draft' after all 4 of the API calls below. Is there some other way to confirm handoff to 'Invoice.send_invoice'? I don't want to add webhooks for this - webhooks don't add any value for this application, and are way too complicated just to get handoff confirmation
3. I've tried the code below both with auto_advance as 'false', and leaving it at the default. Is there any reason to prefer one or the other when just sending one-off invoices? My understanding from the docs is that Stripe won't send invoice reminders to the customer if auto_advance is 'false' - is this correct? Note that I manually call finalize in both cases, to avoid the one-hour delay, but I only call 'send_invoice' for auto_advance false. This all seems to work.

Code as follows:

def raise_invoice(cid, description, cost):
    try:
        invoice = stripe.Invoice.create(
            customer          = cid,
            collection_method = 'send_invoice',
            description       = description,
            days_until_due    = 5,
            auto_advance      = 'false')
        invoice_id = invoice['id']

        item = stripe.InvoiceItem.create(
            customer    = cid,
            description = description,
            amount      = cost,
            invoice     = invoice_id)

        stripe.Invoice.finalize_invoice(invoice_id)
        stripe.Invoice.send_invoice(invoice_id)

        print(invoice['status'])
        sys.exit(0)
    except Exception as e:
        print("Error: " + str(e))
        sys.exit(1)

[Amanda Lee]

Hello,

I've left some answers to your questions below!

The dashboard payments page shows the description as 'Payment for invoice', which isn't helpful - you have to explicitly find and click into the open invoice to find out what it's for. What sets the 'Payment for invoice' text, and can I modify it from the API? This is not the invoice 'description' field, which only goes into the invoice 'Memo'. What I really need to do is set the description for the corresponding PaymentIntent.

Unfortunately there isn't a way to control that description in your requests that create/finalize the Invoice, but you can always update the description of an Invoice's underlying PaymentIntent through the API (https://stripe.com/docs/api/payment_intents/update#update_payment_intent-description).

I need some positive feedback from the API that Stripe has accepted the invoice and has, or will, attempt to email it to the customer. However, the invoice status doesn't work for this. It always shows the status as 'Draft' after all 4 of the API calls below. Is there some other way to confirm handoff to 'Invoice.send_invoice'? I don't want to add webhooks for this - webhooks don't add any value for this application, and are way too complicated just to get handoff confirmation

After finalizing and sending your Invoice it should have a status of `open`, not `draft`. Looking at the code you shared, it looks like you're printing the `status` of the Invoice when it was first created, not the `status` of the Invoice after the final send Invoice request. If you make the following change to your code, it should reflect the latest `status` of the Invoice.

invoice = stripe.Invoice.send_invoice(invoice_id)

print(invoice['status'])

I've tried the code below both with auto_advance as 'false', and leaving it at the default. Is there any reason to prefer one or the other when just sending one-off invoices? My understanding from the docs is that Stripe won't send invoice reminders to the customer if auto_advance is 'false' - is this correct? Note that I manually call finalize in both cases, to avoid the one-hour delay, but I only call 'send_invoice' for auto_advance false. This all seems to work.

To start things off I want to clarify that if you're on an API version after 2018-11-08 (https://stripe.com/docs/upgrades#2018-11-08), then for one-off Invoices `auto_advance` already defaults to `false`. So if you've been testing the behavior differences of setting `auto_advance: false` and not setting it at all (the default) then those will behave the same. If you want to guarantee that Invoices will only be finalized or sent to Customers after an explicit request to Stripe's API then you'll want to set `auto_advance: false`, but if your only goal is to just bypass the one hour finalization lag and you're fine with Stripe automatically sending the Invoice then either value of `auto_advance` will work. However as you already mentioned, `auto_advance` also controls the Invoice reminder emails as well as some other features (https://stripe.com/docs/invoicing/integration/automatic-advancement-collection#toggle-auto-advance) so you'll want to consider than when deciding whether you want to disable/enable auto-advancement.

As a final suggestion, you can completely remove your call to finalize the Invoice. When you make the request to send the Invoice we will automatically finalize the Invoice for you.

Hope that helps!

Amanda