bgerstle_best-practices

[olive valley]

👋 Welcome to your new thread!

⏲️ We'll be here soon! Typically we respond in a few minutes, but sometimes we might take a bit longer if the server is busy or if you have a particularly tricky question.

⏱️ We close idle threads, which makes them read-only. Once a thread is closed it won't be reopened, but you can always start a new thread if you have another question.

🔗 This thread will always be available, even after it's closed. You can find it again using Discord's search, or you can save this link: https://discord.com/channels/841573134531821608/1286705452633292973

📝 Have more to share? Add more details, code, screenshots, videos, etc. below.

[analog fjord]

Hi there 👋 do you have an example Invoice that I could take a closer look at? No big deal if not, I can spend a couple minutes building one in my test account.

Offhand I think the best approach for this is to calculate the difference between starting_balance and ending_balance, but would like to look at an Invoice to double check that:
https://docs.stripe.com/api/invoices/object#invoice_object-starting_balance
https://docs.stripe.com/api/invoices/object#invoice_object-ending_balance

[woven glen]

sorry for the delay, here's one: in_1PzleuD5brjRWvFQpgoaVJeB

[analog fjord]

Thank you! Yup, looks like comparing the two balance values I pointed to, on the Invoice object, will allow you to calculate that $5 was applied to the Invoice's amount from the customer's balance.

[woven glen]

Offhand I think the best approach for this is to calculate the difference between starting_balance and ending_balance, but would like to look at an Invoice to double check that:

this is what I was considering, but I wasn't sure if there are edge cases around when an invoice is finalized and any other invoice that's paid in the meantime

[analog fjord]

Those fields don't lock until finalization, so they'll fluctuate until the Invoice is finalized and locked, then they'll settle and show exactly how the Invoice impacted the customer's balance.

[woven glen]

I know customer balance transactions can have an invoice_id. It would be nice if those were included on the invoice object or at least were queryable directly. AFAICT the customer balance tx API only allows you to list transactions by customer—not by invoice

Those fields don't lock until finalization, so they'll fluctuate until the Invoice is finalized and locked, then they'll settle and show exactly how the Invoice impacted the customer's balance.

Sounds like once the invoice is paid it should be safe to compute the applied credit balance?

[analog fjord]

Once the Invoice is open it's safe to compute the applied balance, since that balance is applied at finalization rather than at the time of payment.

[woven glen]

since that balance is applied at finalization rather than at the time of payment.

🤔 I know we create draft invoices, add invoice items, then call the pay endpoint

[analog fjord]

Oh, if you let the payment request finalize the Invoice, rather than explicitly finalizing it first, then those happen at about the same time.

You can check the applied balance for an open or paid Invoice

[woven glen]

Hm, one of the requirements we had was that credits aren't used unless payment succeeds

here's the invoice.finalized event for the invoice I linked earlier: https://dashboard.stripe.com/test/events/evt_1PzlfFD5brjRWvFQoW4xn7wW

    "status_transitions": {
      "finalized_at": 1726519012,
      "marked_uncollectible_at": null,
      "paid_at": null,
      "voided_at": null
    },

and it shows the credit balance would have been applied at that time (starting=-5 & ending=0)

I'll need to see what happens in a payment attempt failure scenario..

[cold summit]

Hi, taking over and catching up

Can you clarify what you mean with 'one of the requirements we had was that credits aren't used unless payment succeeds'?

[woven glen]

sorry I don't know why I'm not getting notified about new messages

there, changed thread to all messages

ok, so the thinking was that if payment failed for an invoice, that the credits would remain available for another payment attempt, potentially on another invoice

instead, it sounds like Stripe applies the credit balance as part of finalization, which means if a payment attempt fails, the open invoice (which we consider past due) would already have credits applied

I guess that makes sense from a dunning standpoint, so smart retries are re-attempting the same amount

I'll bring this back to my stakeholders, I don't think it's a major issue

one last question, I mentioned above that it would be nice to either include customer balance transactions related to an invoice in the invoice object, or at the very least, list/get the customer balance transaction associated with an invoice

is that on the roadmap, or achievable via some other means? webhook events?

[cold summit]

There should be an event, let me test this to confirm.

[woven glen]

there are invoice events, but I didn't see any event types for customer balance transactions

looks like there's a customer updated event when the balance changes... but still not seeing anything that shows the creation of a new customer balance transaction

[cold summit]

After testing, we send customer.updated event to show you the balance change. However, you wanted to see how the amount change is tied to an invoice and in this case, you would want to look at invoice.paid event and look at the ending_balance and starting_balance. The delta on that is the change in the balance.

[woven glen]

I see. I'm a bit of a stickler for explicit over implicit, so I was hoping to have easy access to the actual customer balance transaction that shows the amount applied to a specific invoice. Inferring from start/end balance works well enough for now, thanks for looking into it!

[cold summit]

Happy to help!

[woven glen]

In case it's not clear, I'm referring to the list of customer balance transactions for customer cus_QrUTQTab18r5Eh. If I call the GET /customer/<id>/balance_transactions endpoint, I get back a list with this balance transaction:

{
  "id": "cbtxn_1PzlfED5brjRWvFQPpbAj5ZV",
  "object": "customer_balance_transaction",
  "amount": 500,
  "created": 1726519012,
  "credit_note": null,
  "currency": "usd",
  "customer": "cus_QrUTQTab18r5Eh",
  "description": null,
  "ending_balance": 0,
  "invoice": "in_1PzleuD5brjRWvFQpgoaVJeB",
  "livemode": false,
  "metadata": {},
  "type": "applied_to_invoice"
}

A nice feature would be to have that included in the invoice object and related webhook event(s)

that way I don't need to compute the balance transaction amount

or at the very least, add an option to get balance transaction(s) for an invoice (I expect there should only be one since credits are applied when it's finalized)