#brel_unexpected
dapper axleBOT
👋 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/1389918108306636893
📝 Have more to share? Add more details, code, screenshots, videos, etc. below.
ebon harbor
Correct, downgrading/cancelling the subscription doesn't automatically close/void any existing invoices. So we'll keep retrying payments automatically according to your schedule for them
You'd need to manually void them if that is your wish, when the user downgrade/cancels
dull rampart
Ok but why $500, so full amount!
Since he had a proration for unused time, the charge would be only $9
ebon harbor
Not sure what proration you're referring to? This was the initial invoice generated when the sub was created
dull rampart
please check the link I sent you. The cuatomer was on trial. After the trial ended, after 10 days customer downgraded to free. So he had to pay only for the used time of 10 days
If you see the logs there is a proration of -491
So why the cuatomer was charged 500 when in fact he also had the unused time
ebon harbor
There's no proration on the $500 invoice: in_1Rc7RbARjJ1na9ElohamjYXQ
Why would be prorate for unused time on a free trial?
dull rampart
No, after trial ended, he used the subscribtion for 10 days
plase check the logs, its there
The payment for the subscribtion was done after user downgraded
because he had no payment method before
ebon harbor
I am looking at the subscription internally. There are two invoices on sub_1RUVQwARjJ1na9ElaboGbmjg:
in_1RUVQwARjJ1na9ElpzydupdD– $0 due, free trial periodin_1Rc7RbARjJ1na9ElohamjYXQ- $500 due, generated at end of trial period
On which invoice do you see proration?
dull rampart
Please check the logs of subscribtion
and see what happened
do not stick to invoices
See the logs, there is something not turning there
Customer paid $500 for only 1% usage
this is not right
ebon harbor
I am looking at the logs. Any proration would be applied to an invoice. You claim there's $491 credit for unused time but I don't see it anywhere
dull rampart
See the logs of the subscribtion. There is a log for unused time
dapper axleBOT
ebon harbor
Can you provide a screenshot of what you're referencing?
ebon harbor
Paste the evt_xxx ID please
dull rampart
This is the user with the problem
He has just ine subscribtion
check it and see that is not normal please
ebon harbor
That's not what I asked for. Can you paste the evt_xxx ID from the screenshot that references proration
coral saffron
👋 taking over for my colleague. Let me catch up.
ok so I looked at the subscription and here's what I've found
this is the request where your customer downgraded the price
basically you didn't pass the proration_behavior which defaulted to create_prorations
this means that your customer now has a pending invoice item that you can see based on this event https://dashboard.stripe.com/events/evt_1ReHnoARjJ1na9ElG4tfBFxq (the one that my colleague was asking you to provide)
this invoice item will wait until the next generated invoice (whether it's manually created and you include the pending invoice items for that customer or the next billing cycle's invoice) to be applied
if you want the proration to be automatically applied, you need to pass proration_behavior: 'always_invoice'
and depending on whether you want the billing cycle anchor to change or not you would respectively pass now or unchanged
does that make sense now @dull rampart ?
dull rampart
Hello thank you for this explanation
What does not make sense to me is the fact that customer is charged the full amount of subscribtion when he in fact downgraded
This is very confusing for the customer.
coral saffron
he's still not charged anything
dull rampart
yes he is
coral saffron
there isn't any payment that happened on that day
dull rampart
I refunded him $500
coral saffron
you should have just created an invoice with the pending invoice
dull rampart
please check the subscribtion
coral saffron
which would have generated the customer balance
dull rampart
I didn’t understand this
can you please tell me the amount customer was charged
and what I refunded
and the balance thing
You see the refund of 500 that I have done
Where did the unused time amount go?
coral saffron
in the invoice item that was created
and will show on the next invoice
on the next billing cycle
ebon harbor
The default parameter for proration_behavior is create_prorations, which creates proration invoice items when applicable. These proration items are only invoiced immediately under certain conditions.
https://docs.stripe.com/billing/subscriptions/prorations#default-behavior
Neither of those conditions are applicable in your case, so as my colleague stated, the prorations will be pulled into the next invoice for the customer/subscription. You can preview this via this endpoint: https://docs.stripe.com/api/invoices/create_preview
In future if you want to immediately apply proration then pass proration_behavior: 'always_invoice' in your update call
Outside of that, please explain what points of confusion remain and we can do our best to explain
dull rampart
my confusion is that it does not make sense to be applied on the next invoice since customer is on free plan and the invoice amount is 0
Also why it does not appear as customer balance then?
I dont see the unused time as customer balance
ebon harbor
my confusion is that it does not make sense to be applied on the next invoice since customer is on free plan and the invoice amount is 0
That's just how it works as per the link above. If you tell us not to immediately apply the prorations, then they are added on the next billing cycle automatically. Even if the customer is on a 'free' plan invoices are generated so we'd apply it to that and only then would the credit be applied to the customer balance
Also why it does not appear as customer balance then?
As stated, that would happen after the proration is invoiced. The credit amount would move to the customer balance
dull rampart
You previously told me that customer was not charged $500. Can you please confirm the opposite now? That he was charged $500 on his card? I want to make sure this is the case because I did a refund to him. And also my question is - Since I did the refund is the proration amount also available?
Normally it should not
ebon harbor
I don't think anybody said they weren't charged $500? Pretty clear they were. Here: https://dashboard.stripe.com/payments/pi_3Rc8OrARjJ1na9El1R3UP9X9
And also my question is - Since I did the refund is the proration amount also available?
Yes the prorations still apply and will be credited to the customer balance. You can decrement that manually to make it 0
dull rampart
Can I do it now? How? I dont see any customer balance
ebon harbor
> Also why it does not appear as customer balance then?
As stated, that would ha...
As explained
dull rampart
So I should wait 1 year? The next invoice for the subscribtion is after 1 year?
ebon harbor
Well you can decrement the balance now for the same amount then when the next billing cycle hits it'll neutral out from the credit applied by the invoice
dull rampart
I am not sure it is completely safe. The discount is applied on the invoice anyway. So if the invoice for any reason changes the amount to something positive, it means that the credit will be applied anyway
ebon harbor
What are you actually trying to achieve here?
dull rampart
Normally what happens with a customer with credit balance below 0. In general, that amount is charged on the upcomming charge?
I am asking in general
ebon harbor
Well a negative balance (e.g. -100) is a credit meaning you owe them money. A positive amount would be a debit and yes they're automatically applied to next invoice: https://docs.stripe.com/invoicing/customer/balance#working-with-credit-balances
dull rampart
Since a credit of 491$ will be applied on the customer next invoice, this means I have to define a positive 491$ credit to user or negative?
I think negative means they owe me money
so the opposite of what you previously mentioned
ebon harbor
Since a credit of 491$ will be applied on the customer next invoice, this means ...
You want to apply a debit, which is a positive amount
ebon harbor
I think negative means they owe me money
Nope:
**Credits are negative values (a reduction in the amount the customer owes) **that you can apply to the next invoice. Debits, on the other hand, are positive values (an increase in the amount the customer owes) that you can apply to the next invoice.
https://docs.stripe.com/invoicing/customer/balance#credits-and-debits
dull rampart
Ok lets say I apply the credit that they owe me. And then lets say an invoice is created for them before the upcomming invoice of the subscribtion. Does this mean the credit will be applied on the new invoice?
ebon harbor
Yes
dull rampart
But then this becomes very frustrating for them
ebon harbor
Then you'd need to workaround that I'm afraid. You can remove the proration line item after the invoice is created if you prefer
dull rampart
I just need to reduce the balance applied on the upcomming subscribtion invoice that I have now
This will resolve the issue
the invoice for 2026
ebon harbor
AFAIK there's no way to do that
dull rampart
So what do you suggest me to do in the future to not be in this situation?
ebon harbor
Pass proration_behavior: 'always_invoice' in your update calls. That way the credit for unused time would of been immediately applied to the customer's invoice
dull rampart
when you say customer’s invoice you mean the next invoice?
Because in this case the update was a downgrade
Would the 500$ invoice in this case be just 9$ if I passed always invoice?
So the invoice that was already created before the update, is going to change the amount?
Would this be the case?
sonic otter
when you say customer’s invoice you mean the next invoice?
Hi there 👋 jumping in as my teammate needed to step away.
They used the term customer invoice generally there, they aren't referring to any specific Invoice object. They are trying to articulate that if you use always_invoice as your proration behavior, that will cause an Invoice to be immediately generated as part of the Subscription update, so the customer can immediately be charged or credit for the resulting prorations.
sonic otter
Would the 500$ invoice in this case be just 9$ if I passed always invoice?
I don't understand this question, I don't grasp how an Invoice can be both a $500 invoice and a $9 invoice.
dull rampart
Let me re-explain what happened step by step Toby
sonic otter
I've read the thread and have a pretty good grasp of the situation. I'm just less confident I understand what you're asking.
Have you tried using our test clocks to step through all of these flows in test mode and see exactly how the Subscriptions and Invoice will behave based on your code and account settings?
https://docs.stripe.com/billing/testing/test-clocks
dull rampart
- Customer cus_SPJY8k4mO7zx7x has a trial Subscribtion
- Subscribtion with id: sub_1RUVQwARjJ1na9ElaboGbmjg
- When subscribtion ended Stripe atempted to get the payment for the new billing cycle
- The first attempt failed as customer did not have a payment method
- The second one as well
- Customer downgraded to free plan after a few days. This resulted in a proration of -491.81$
- Customer added a payment method
- On the next retry Stripe charged him 500$ (Here becomes the confusion)
So customer was charged 500$ eventhough he was on free plan. At least he would be charged just 9$ (500$ - 491$)
Then I did a refund of $500 to customer
- I dont see anywhere where the 491$ is, there is no balance. Also customer is confused why he was charged $500 when he was on free plan and he just used a few days of the plan
Since this is the default behaviour, is this normal? Is this how this situations happens on other apps?
I want to say an explanation to the client about this situation. Is this normal how this should work?
sonic otter
It will take me a bit to write up a thorough answer, but I don't think you should fixate on default behavior. You should focus on understanding the options available in our system, and then map them to your business requirements, so you build a flow that meets your needs (as opposed to one that just behaves according to defaults).
dull rampart
What would I have done so that this flow would have ended up in a charge of just $9 or $0 since user is in free plan?
Please consider the order of steps above
sonic otter
Customer: cus_SPJY8k4mO7zx7x
Subscription: sub_1RUVQwARjJ1na9ElaboGbmjg
Things in your description that don't appear to be accurate:
- When subscribtion ended Stripe atempted to get the payment for the new billing cycle
The Subscription did not end. It's free trial period ended, at which point an Invoice was generated to charge the customer $500 for the new billing period. (Invoicein_1Rc7RbARjJ1na9ElohamjYXQ)
oh, I see your confusion. You think updating the Subscription will change the amount of the existing open Invoice, which is incorrect. The already open and finalized Invoice will not change the amount that it is for.
I dont see anywhere where the 491$ is, there is no balance. Also customer is confused why he was charged $500 when he was on free plan and he just used a few days of the plan
How are you trying to look at this? In the dashboard, or by retrieving and looking at objects from the API? If the latter, what objects are you looking at currently?
dull rampart
I am looking on the dashboard. I just want to know how can I avoid charging the customer the total amount of subscribtion when in fact at the moment of payment he is in the free plan and does not make sense to charge him the full amount? Does this seam reasonable to you?
How would I charge him just $9 in this case?
sonic otter
The pending Invoice Item with the proration credit is shown in the Upcoming invoice section on the Subscription page.
https://dashboard.stripe.com/subscriptions/sub_1RUVQwARjJ1na9ElaboGbmjg
sonic otter
How would I charge him just $9 in this case?
- Void the previous Invoice for the full amount for the billing period, so that Invoice doesn't get paid.
- Set
proration_behaviortononewhen upgrading the Subscription (because you want to use your own proration calculation logic instead of using the way we calculate prorations) - Generate a new Invoice Item and Invoice for the $9 you want to charge the Customer
- Finalize and pay that Invoice
But it sounds like you'll also want to add logic to your flow to check whether the first Invoice is paid or not, I'm not sure what you want this flow to look like if the customer actually paid the first Invoice before the downgrade.
dull rampart
No, I want your proration logic. Is just that I want that proration to be applied immediately
I dont like the fact that you apply it on the next invoice
And also I dont like the fact they I refunded the customer, and he continues to have the applied credit on next invoice
sonic otter
No you don't, or at least what you've been saying so far makes it sound like you don't. You want the customer to be charged $9. Our proration logic is to charge them $500 and then credit them back $491.
You can't think of these payments as all being one payment. You need to think of every Invoice as a distinct and single transaction.
dull rampart
But why the credit was not taken from customer balance when I did the refund
now the customer has the refund and also credit
sonic otter
It wasn't applied to the credit balance yet, because the negative amount Invoice hasn't been generated yet, because the Subscription update request didn't specify proration_behavior, so the default behavior was used which is create_prorations which creates an Invoice Item for the prorations which will be pulled into the next Invoice that is generated (on Jun 20, 2027).
dull rampart
But if another invoice gets generated before 2026, will that change? Will the balance be applied on the new invoice?
sonic otter
Yes, I'm pretty sure it will, if another Invoice for this Subscription is generated.
dull rampart
I mean whatever invoice for this customer. Not from this subscribtion
sonic otter
Which is why I explicitly specified for this Subscription.
dull rampart
So only for this subscribtion. On the other hand, if it was a customer balance? For example the next subscribtion invoice in my case is 0$. This means that after that the balance witll be applied to customer? And after that he can pay whatever with that balance?
sonic otter
Customer balances are automatically applied to the next finalized Invoice for the Customer.
https://docs.stripe.com/billing/customer/balance#:~:text=The invoice balance automatically applies toward the next invoice finalized to a customer.
dull rampart
So currently it is not considered as customer balance. It will be considered after the payment of the invoice in 2026?
sonic otter
Correct, right now it is a pending Invoice Item. Once that Invoice Item is added to an Invoice, and that Invoice is finalized, that is when the customer balance will be adjusted (based on what other items, if any, are pulled into the generated Invoice).
dull rampart
Sorry for lots of questions but this is a very important part of my app.
So in the future, to automatically apply to the balance I need to change the proration_behaviour?
So that the refund would also collect the funds from the balance directly?
To not endup like in this situation that customer has balance and also the refunded amount
sonic otter
to automatically apply to the balance
What do you mean by this? If you're talking about the customer balance, it has nothing to do with proration_behavior. Customer balances are always automatically applied to the next finalized Invoice for the Customer, neither you nor the customer have any control over that.
dull rampart
But how can I make sure that like in this case when I refund to also remove the applied balance that will take effect after the payment of next invoice
You understand what I mean? Maybe I am not clear
sonic otter
You will need to make an additional request to manually edit the customer's balance. The refund process will not do that for you.
Instructions for modifying that balance, via the dashboard or our API, can be found in this section:
https://docs.stripe.com/billing/customer/balance#modifying
dull rampart
What should I do now? I want to make sure my customer does not use that balance anymore because I have already refunded him
sonic otter
That's tricky, because they don't have a balance yet. I wouldn't suggest adjsuting the balance now, because it will get pulled into any other Invoices generated for the Customer, and I don't have enough context on your flow to understand whether that may happen for a one-off Invoice or a different Subscription.
My thinking is you wait for the next Invoice to be genearted, and then make an adjustment to zero-out the customer's balance.
dull rampart
But how can I keep track if customer generated another invoice on meantime that has a value and uses the balance?
it can happen even tomorrow
sonic otter
Look at you logs
Look at your dashboard
I'm not really sure how to provide advice there without understanding your flows, how do you normally check your customers activity?
dull rampart
The problem is not the logs, is on the fact that a charge can happen at whatever time
Tomorrow they can subscribe to a new subscription
that costs 400$
sonic otter
That won't include the pending invoice item for this subscription
Or are you seeing something different when you replicate this scenario in testmode?
sonic otter
so not a new Subscriptoin
dull rampart
Does it mean that 291$ will be applied?
sonic otter
Depends on how you structure the update request, and whether you calculate prorations for the update. You can test this in testmode to see exactly how the system will behave.
The Invoice will pull in the $-491 pending Invoice Item, but I can't comment on what the total of the Invoice would be without more context.
dull rampart
How can I be safe on updating that subscribtion in the context we are speaking?
sonic otter
What does safe mean to you?
dull rampart
I dont want the balance to be applied on nay way in the future for that subscribtion
dapper axleBOT
sonic otter
There is no customer balance right now, there is no balance to be applied to a next Invoice.
The proration Invoice Item has already been created, it's too late to prevent it from being involved.
dull rampart
If customer updates the subscribtion tomorrow to a paid subscribtion what will happen? Will the proration amount be applied?
sonic otter
Depends, how are you doing that update request?
Ah, actually, it doesn't depend.
Since you'd be upgrading from a free Price to a paid Price, which will force a billing cycle anchor reset, which will force a new Invoice to be generated for the Subscription, which will pull in the pending Invoice Item for the previous proration.
sonic otter
$-491, but yes
dull rampart
That's what I want to prevent. The customer should not use that
I have already refunded him
and I don't know when it will happen
to prevent that
sonic otter
You could proactively adjust their credit balance with an amount to cancel out that proration, but if an Invoice is generated for the Customer that isn't part of this Subscription that we're talking about, then that Invoice will consume the balance amount you create.
dull rampart
ok, so there is not best route
I have another question. I know that subscribtion remains in past_due when Stripe is unable to collect payment. On the last attempt the subscribtion is marked as unpaid? Will Customer be charged if he adds a valid card after that period?
sonic otter
The state the Subscription transitions to if all payment retries fails is dependent on the settings you've configured in your account. You can see and adjust them here:
https://dashboard.stripe.com/settings/billing/automatic
in the Manage failed payments for subscriptions section
What a Customer will be charged, is a little hard to answer. If your real question is how to prevent the customer from being charged, then you'll also want to void the still-open Invoices.
While automatic payment retries may have ended, it's still possible for your system to trigger a payment attempt, or possibly for the customer to access the Customer Portal and pay for it themselves. Or they may do the same by accessing the Hosted Invoice Page for the invoice. Voiding the Invoice is the best way to prevent it from being paid.
dull rampart
Yes ok but my question is not related to the situation. IS in general. Does Stripe attempt to charge the customer after all configured retries have been triggered?
After the last one does Stripe always mark the stubscribption status as unpaid?
sonic otter
Yes ok but my question is not related to the situation. IS in general. Does Stri...
No, if our automatic retries have been exhausted, we won't try the payment again. (but that doesn't mean that no payment will be attempted, just that we won't be the ones who triggered it)
sonic otter
After the last one does Stripe always mark the stubscribption status as unpaid?
This is dependent on your account settigns, there isn't a general answer to this question.
dull rampart
ok, thank you but what if customer had downgraded to free plan before the last charge retry on your end?
sonic otter
Then you have the situation that this whole thread is talking about. What specifically is still unclear?
dull rampart
I mean why would the subscribtion status change
dull rampart
Because after 3 retries I have marked the subscribtion to be markes as unpaid
But it would make sense if we are talking ont he state of the subscribtion before the update
If customer changes it, like it downgrades to free
Will subscribtion pass to unpaid after all retries?
sonic otter
This is tricky to answer, because the state of the Subscription is dependent on it's most recently created Invoice, so the answer to your question depends on how you're structuring the downgrade request and whether that will generate an Invoice.
If it doesn't, then the Subscription status will flow to whatever you have set after the retries for the existing Invoice all fail.
If it does create a new Invoice, then the Subscription status will flow to whatever you have set once all payment attempts for the new Invoice fail.