zach_best-practices

[wet timber]

👋 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/1238132143125692416

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

[fathom gale]

Hello

Mostly you have to handle this yourself

[marble tinsel]

hi bismarck

[fathom gale]

You control reporting usage here

So you would ensure they have an active Subscription for that Product

[marble tinsel]

Hmm, with old usage though, you had to be susbscribed to the product

in order to send usage

because you provided a subscription item when sending usage

[fathom gale]

Correct, I don't believe we enforce that with the new Meters API

As it provides greater flexibility

[marble tinsel]

Greater flexibility only if #2 of my questions is solved for.

Or else you have a meter record, but no way to bill for it

[fathom gale]

Yeah I actually haven't tested that but I assume it does bill for the collected usage

So recommend testing that out

[marble tinsel]

I did test it.

It didnt work.

I expected the same.

[fathom gale]

Can you share the Subscription ID?

[marble tinsel]

Of course

mtr_test_61QNYPhe3PVm6agEK41Btu9lUy7zyD1k

this is my meter

cus_Py1iM9zjERh34m

this is my customer

sub_1P85fWBtu9lUy7zyjkSxJ4pK

[fathom gale]

Thanks, looking

[marble tinsel]

is my subscription

Also as I try to gather this info for you, one other question

is there a way to see all meter events?

vs just the live meter events (which only shows a handful)

[fathom gale]

No you can only list meter event summaries: https://docs.stripe.com/api/billing/meter-event_summary/list

If you want each individual Event you would need to store that on your end

[marble tinsel]

even through API , i cannot fetch entire list of meter events?

[fathom gale]

Correct. That is the same as how the Usage API worked (and works)

[marble tinsel]

with an idempotency key, can i fetch an individual record?

[fathom gale]

Not sure what you mean by that

There is no way to retrieve an individual Meter Event via the API

Okay so for your Sub example it looks like you updated the Sub and reported usage but an Invoice has not been cut yet to charge that usage

So you would need to advance time using the test clock and I do believe you should see that usage charged

[marble tinsel]

Uhhh

so for old usage right,

it would say "next invoice for x amount"

which would be all the usage records recorded so far in the billing period

so that the customer would be able to see real time, what their current usage is

[fathom gale]

Ah

One sec

[marble tinsel]

if my customer goes into the portal mid month

i would expect them to see how much they have used alreaedy this month

[fathom gale]

Yep me too

I do see you cleared usage on update but that shouldn't matter here as you reported usage after that

Can you advance time just so we can rule out there being a preview bug ?

[marble tinsel]

sure

I put it to the End of this month

its spinning will report when its done

[fathom gale]

Thx

[marble tinsel]

it says its done

do you need a screenshot?

[fathom gale]

Nope

[marble tinsel]

in_1PEY3jBtu9lUy7zybTE49Spa

[fathom gale]

K thanks. I'm still looking

[marble tinsel]

this is the invoice it created

still 0$

[fathom gale]

Going to need a few mins to determine whether expected for some reason or not.

[marble tinsel]

sure. take your time

[fathom gale]

Okay just tested myself and does seem to work on my end so need to find out what we are doing differently

[marble tinsel]

sure, im glad to know thats the case.

price_1PEKx9Btu9lUy7zy2euvo5vB

this is the price

i see it linked to meter

mtr_test_61QNYPhe3PVm6agEK41Btu9lUy7zyD1k

which has a ton of usage

[fathom gale]

Yep I'm seeing the same, and you reported that usage during that current period for the Sub (after update) so it does seem like it should apply.

[marble tinsel]

and product prod_Py0TOKjhpec4ie in the pricing table

shows the price, with 1 active sub (which is my customer)

[fathom gale]

Yeah very weird -- it is all working fine fo rme. Each time I update and then report usage it shows on the preview.

What if you report usage now for that Sub you are testing with

During this next period (between May 21 - Jun 21)

Can we see if it correctly adds that if you report another meter event for that time period?

[marble tinsel]

OK, let me see what I can do

[fathom gale]

Oh I figured it out

You reported for the wrong Customer ID I think

[marble tinsel]

we have multiple customer IDs hitting that meter

[fathom gale]

So when I look at your Meter Event request it is for cus_Py1kSSYgKKJvgG so that usage should only apply for that Customer

[marble tinsel]

cus_Py1iM9zjERh34m is what i have updated

it has usage from yesterday against the same meter

but the subscription changed yesterday evening

because basically what was happening was the product price was pointing to a different (test meter) meter name.

So i was reporting usage to a meter, that the subscription for the customer wasnt there for

(hence my question #1) about not preventing this

So then i did a change to the subscription, hitting the same product, but a new price which should of pointed to the correct meter (that usage was being reported against)

i expected it to now show me a balance for that user, because usage was reported for that customer.

are we saying that old usage, is in fact not going to ever show

and instead it will only show usage in the future ?

let me try and send 1 agains thtis customer right now.

FYI i sent more usage

to this customer

0927cfb4-0360-4649-ab9b-b1aea35aa20f

is the identifier

still i see no balance

[fathom gale]

A Meter is associated to a Price and that Meter charges based on an event name. A Meter Event gets associated to a Customer and also specifies the Event name. For the Metered usage to apply there must be a Subscription for that Customer with the Price associated to the Meter and the Meter Events must specify that Customer.

So https://dashboard.stripe.com/test/logs/req_44RtXAtLNLAEvg looks to be the requst you just made

Let's step through it

It applies the Meter Event with Event name page_processing to cus_Py1iM9zjERh34m

That Customer has a Subscription currently: sub_1P85fWBtu9lUy7zyjkSxJ4pK

That Subscription is using price_1PEKx9Btu9lUy7zy2euvo5vB

[marble tinsel]

correct

and that price is connect to meter

[fathom gale]

That Price has mtr_test_61QNYPhe3PVm6agEK41Btu9lUy7zyD1k

Yep stepping through slowly to make sure I don't make a mistake

[marble tinsel]

and event page_processing

[fathom gale]

Hmm yep. However that Meter Event you just created is not showing up on that Meter...

Okay let me grab a colleague for a second pair of eyes.

[marble tinsel]

really?

i saw that meter event very clearly

it is now off the screen because more load has come

(why i was was asking if theres any place to see more meter events than just the 10)

[fathom gale]

Ah

[marble tinsel]

i can send another and show you screenshot

[fathom gale]

Wait wait wait

That Customer does have a test clock that is set fro May 31

The usage you just reported is not within the current billing period

You would need to create a new Meter Event with a timestamp in that actual period

[marble tinsel]

can i undo the test clock to pre may 31?

[fathom gale]

No unfortunately can't go backward

[marble tinsel]

can i cancel the test clock?

[fathom gale]

No

[marble tinsel]

or is this customer forever a month ahead?

[fathom gale]

Yes

[marble tinsel]

thats kinda funny

[fathom gale]

You can delete that Customer

And/or create a new one

Or pass a timestamp to your Meter Creation that is within the current period based on the clock

[marble tinsel]

I can send a timestamp for that period

[fathom gale]

Yeah

[marble tinsel]

Current simulation time:
May 31, 2024
|
7:34 AM PDT

so what timestamp would work

[fathom gale]

API is UTC based

1717255770 works

[marble tinsel]

may 21st is the alst invoice date

[fathom gale]

That is 6/1/2024

[marble tinsel]

ok, but for my understanding

if i sent 05/30

would that register ?

[fathom gale]

I believe so, yes, as it is within the current billing period

Needs to be between 5/21 - 6/21

For this Sub to pick it up

[marble tinsel]

ok

sending something now

[fathom gale]

👍

[fathom gale]

Yeah that's the wrong Customer ID

That Customer doesn't have a clock

So you can't set it to the future

I think this has been the problem all along

But we will find out in a sec

You need to be using cus_Py1iM9zjERh34m here

Okay yeah so I was also wrong

You can't put it in the future

[marble tinsel]

that was what i used right?

[fathom gale]

But you can do May 31

Or before

[fathom gale]

I gave you a bad timestamp

Yep sorry, I was looking at https://dashboard.stripe.com/test/logs/req_aGQiiRvO2ao5p6 before

Which was your first attempt

Which used cus_Q4IukWt60QeK2G

But yeah sorry, I shouldn't have given you a June 1st timestamp

I was focused on the billing period

[marble tinsel]

np at all

[fathom gale]

Not the test clock's timing

[marble tinsel]

let me send a new one for may 30th

[fathom gale]

So you need a timestamp equal to or before the test clock, but during this billing period for the Sub

Yep that sounds good

[marble tinsel]

ok

[fathom gale]

Yep looks like it worked

[marble tinsel]

that seems to have worked

[fathom gale]

Yeah so I think the problem all along was a mix up of Customer IDs

[marble tinsel]

so generally, speaking

the "issue" from my perspective is

the new metered billing does not make sure a subscription is enabled, before allowing usage to be reported for a customer

thats not a big deal

but then after you have sent usage to a meter, for which a customer didnt have a valid subscription

there is no way to retrieve that usage, as you have no way to see usage events

[fathom gale]

You would look at the summary if you need to understand the usage that will/would have applied.

[marble tinsel]

nor, will those past usage events, get billed for, even though usage was reported during the billing period

[fathom gale]

Also you can backdate Subscriptions

Which is why I think we do allow for usage without an active Sub

[marble tinsel]

but in this case

the subscription date didnt really change

what changed was the price against which the product was being charged

[fathom gale]

Sure but that just means that the metered usage for that Price has to be within the billing period

[marble tinsel]

it was though originally

like before i did the test clock

[fathom gale]

For a different Price though

That Price is no longer applied to the Subscription at that point of update.

So the usage doesn't "carry over"

Is that what you are expecting?

[marble tinsel]

well that usage didnt get tagged to any price

[fathom gale]

If so, you shouldn't update the Price but instead add the new Price as a second item

[marble tinsel]

even though it was metered

[marble tinsel]

from a product perspective or from a subscription perspective?

on the product to this day, there is old and new price

[fathom gale]

From a Subscription perspective

The Subscription only cares about the Price

That is what it will charge based on

Maybe it would help if we discuss what you are trying to solve for?

Like what is the actual scenario here?

In what case are you applying usage to a Meter that is not yet associated to a Price that is not yet associated to a Subscription ?

[marble tinsel]

Yea for sure.

This isnt an "on purpose case"

this happened because our product/price/subscription was not correctly set

in this case the event name on our original price

was abcd

when it whould of been abcz

should*

but we started sending usage through

now the quesiton is how to recover

i switched the event name, which required me to create a new price

for the product

[marble tinsel]

then i changed the subscriptions to point to the new price

but those meter events, the usage that happened

while the wrong price was configured

are now "gone" from a stripe perspective

yes i have logging on my end

[fathom gale]

They aren't "gone"

You should still be able to list out the summaries, no?

To see the aggregate and then you could apply that usage to your new Meter

[marble tinsel]

i dont have a new meter though

its the same meter

[fathom gale]

That's fine, you would need to create corresponding Meter Events for the Customer for the current period with the new Price.

However, imo it would be cleaner to just create a new Meter

But that would likely also require changing the event_name which you may not want to do

[marble tinsel]

yea, i dont want to change event_name for sure

so I would need to resend the same events to the meter

but now the meter metrics/summaries would be out of wack numbers wise

because i would be 2xing this traffic against the same meter

[fathom gale]

https://docs.stripe.com/api/billing/meter-event_adjustment

You want that

Oh we have a 24 hour limit for that

😅

[marble tinsel]

🙂

[fathom gale]

Hmm yeah if it has already been >24 hours then you are indeed going to have bad metrics for that Meter. So only way to get that clean would be to create a new Meter

[marble tinsel]

yea... thats gonna make things hard

[fathom gale]

I think the other option you could explore is trying to create a new Sub that is backdated with the "wrong" Price

Then charge that

Then update to the "right" Price

You would need to test that out in test mode

I've not tested that so don't know 100% if that works

[marble tinsel]

is there any UI to meter summaries?

or is it all API

[fathom gale]

Believe API-only

[marble tinsel]

basically how would I know the difference between something that has been correctly send to meter and billed vs something correctly sent to meter, but not billed

because no subscription was there

[fathom gale]

I can't tell you that -- you know what is "correct" and "incorrect" and you would have to evaluate what you have charged your Customers so far versus what they should be charged

Likely it looks like listing Subscriptions/Invoices

To see what has been charged. And listing out Meter Summaries

[marble tinsel]

uhh, but im hands off once i send to a meter

[fathom gale]

To understand what kind of Usage you reported

[marble tinsel]

i expect everything sent to a meter

is going to get billed

but now we are saying, even if u have sent to a meter

[fathom gale]

Right so you would need to look at what was actually billed

[marble tinsel]

its not necessarily billed

[fathom gale]

That is possible, yes.

I'm happy to file feedback about this internally

Not sure if we could send some kind of warning or something

[marble tinsel]

please do

yea, something

cause last thing we want to do is say we reported usage to stripe meter

but we didnt actually bill the customer

[fathom gale]

Yeah that's fair -- I think there are legitimate use-cases where we want to allow this which is why it isn't blocked.

[marble tinsel]

it would also be super helpful to be able to send the unique identifier of the meter event

and get some sort of status about it

[fathom gale]

But I'll certainly report feedback to see if we can find a happy medium

[fathom gale]

I'll include that as well

[marble tinsel]

great

I guess for now i need to play some more with this

so if i do in fact want a price change

your suggestion is

keep the existing subscription

with the product with old price

and add a new line to the subscription

with product with the new price

correct?

i guess i am asking how real price changes work with meters

[fathom gale]

So mostly it depends.

You don't want to update the Price and remove the previous Price if that Price currently has reported usage.

[marble tinsel]

reported usage for the current customer or for any customer

I guess maybe its better if i give u the scenario and you tell me how it should be done?

[fathom gale]

Yeah that is easiest.

[marble tinsel]

Lets say i am charging my customer per page to read a book (not actual use case, but should simplify)

today i charge them .02 a page

so i have a customer, product is book reading, my customer is subscribed to book reading, the price is .02 cents per page and i have a meter where i send an event everytime i read a page of the book

its mid month, my eyes are tired from all the reading

i want to now charge .03 a page

what do i do

[fathom gale]

Okay and what is the goal? Charge them for the amount of pages they have read so far at $0.02 and then charge for remaining pages this period with $0.03 ?

[marble tinsel]

correcet

[fathom gale]

And then going forward charge all at $0.03

[marble tinsel]

yes

[fathom gale]

Okay in that case then yes you would just add another Subscription item with the Price for $0.03

So the Sub now has 2 Prices with 2 Meters

You then stop reporting to Meter 1 (the $0.02 Price) and start reporting to Meter 2 (associated to the $0.03 Price)

[marble tinsel]

hmm 2 meters?

[fathom gale]

Then at the end of the period you can update the Sub to remove Price 1

[marble tinsel]

why would the meter change

[fathom gale]

Whoops sorry

Meter doesn't need to change, the Event name

(Still on old usage-based concept)

So just one Meter but different Event names for your Meter event reporting

[marble tinsel]

but event name to meter is 1 to 1

you can only have 1 event name on a meter

also the event didnt really change, its still " i read a page"

[fathom gale]

Yep yep yep right. So back to what I said before, you do need 2 meters here.

And the event is technically different if they have different costs, right?

[marble tinsel]

the event is the same, they read a book

the price is different

the price should be derived

by what subscription is active against that customer

for that product, that the meter is collecting usage on

[fathom gale]

Ah yeah okay okay I see what you are saying

One min

Okay yeah I was telling you the way we used to recommend handling this with the legacy flow

But you are right, that doesn't work with Meters API

Since you associate one Meter to multiple Prices here

So instead what you would do is you would check the current usage just before update and you would create an Invoice Item for the amount that corresponds with that usage

That Invoice Item will get picked up by the next Invoice for the Sub

Then you update the Sub to the new Price (and delete the previous Sub Item and use clear_usage: true -- https://docs.stripe.com/api/subscriptions/update#update_subscription-items-clear_usage)

[marble tinsel]

OK, so you are recommending a clearing line basically

im doing a 1 time invoice line item

for the usage against old price

i guess my question is, how do i add a invoice line item mid month

my understanding was invoice line items could be altered/edited during draft invoice time period

which is like the last 3 days of the month

[fathom gale]

Invoice Item

Not Invoice Line Item

You use https://docs.stripe.com/api/invoiceitems/create

[marble tinsel]

OK

[fathom gale]

You can do that at any time, it creates an Invoice Item that is then picked up by the next finalized Invoice

[marble tinsel]

so this is basically a one time charge

[fathom gale]

Yeah pretty much.

[marble tinsel]

gotchya

pretty awkward way of doing it

[fathom gale]

You can write a corresponding description to have the item represent the metered usage

[marble tinsel]

im sure its possible

yea

it just seems like price should be based on dates "active"

[fathom gale]

Why do you update from $0.02 to $0.03 for the same Product?

[marble tinsel]

because the product is still a page read

it has just gotten more expensive

[fathom gale]

Yeah okay so this is more like a one-time migration then, yes?

[marble tinsel]

not really

this is like inflaiton hitting the book reading

it can happen 3x a year possibly

maybe tomorrow we need to charge .05 a page

[fathom gale]

Yeah I understand, but more inquiring whether it is a customer-driven update for some reason.

[marble tinsel]

no its not customer driven update

this is us saying you were paying .02 per book reading

now we are charging you more

[fathom gale]

Why not just charge them at time of update in that case?

Instead of keeping the billing period the same

Especially if you control this, you could just update at the end of the natural billing cycle

That would work too

[marble tinsel]

yea, it is a potential option

[fathom gale]

Doesn't really seem like there is much reason to update mid-cycle for something like this?

[marble tinsel]

we have no business reason to time it aligned with billing cycles

in that our CEO tomorrow can decide that starting monday prices change

but im sure if this is some limitation

we can say it is

it just seems weird, that a mid cycle price change is so hard to handle

i would think that the price for the first part of the cycle

would be based on your usage during that time period

[fathom gale]

It is because proration doesn't exist with metered billing

[marble tinsel]

and what the active subscription was

yea, but this is less about proration from a standard proations sense right

you already are doing some math

to come with the "next invoice will be this dollar amount"

you have that number from calculations being done in stripe

based on usage and current subscription

when that price is then changed you would think it would be able to collect that number, and say this is the number until this point

[fathom gale]

I hear you, but that just isn't how it works. I don't have the design docs in front of me but there are an extremely wide variety of use-cases here.

[marble tinsel]

oh i am certain there are wide use cases

this just seems like it is one thats missed

in that it doesnt seem all that complicated of a scenario

[fathom gale]

Our API mostly tries to be un-opinionated

Which allows for flexibility

[marble tinsel]

un opinionated is great

[fathom gale]

But yes, does mean sometimes more handling on your end.

[marble tinsel]

yea, but then usually some options /flags to enable certain opinions

🙂

thats ok

I think i got what I needed from you today, ill start coding and see where I get

[fathom gale]

Yep, don't know the exact history here for the metered billing design

Sounds good

Best of luck, pop back in if we can help further

[marble tinsel]

im sure u will hear from me in the future

🙂

thanks!

[fathom gale]

Haha sounds good