oleg-codaio-update_subscription | Stripe Developers | Page 1

spark berry Sep 9, 2022, 2:19 AM

#

hello! you'd probably want to look into using Subscription Schedules : https://stripe.com/docs/billing/subscriptions/subscription-schedules/use-cases#resetting-anchor

golden crane Sep 9, 2022, 2:19 AM

#

Let's say for instance that there is an annual subscription with a term of March 1, 2022 - March 1, 2023. The customer would like to update the subscription to a different plan, which also come with a one-time setup fee. On Sept 8, 2022 at 1:05pm, they make the change. Here's what I want to happen:

Subscription is updated with a new billing anchor - Sept 8, 2022 1:05pm - Sept 8, 2023 1:05pm
Invoice sent out containing these line items:
1. Unused time on 1 × Subscription after 08 Sep 2022
2. 1 × Subscription (per seat) - [Sept 8, 2022 - Sept 8, 2023]
3. Setup fee [Sept 8, 2022 - Sept 8, 2023] - discountable = false and also containing additional metadata

#

Here's what I tried:

Using subscriptions.update with add_invoice_items. That works as far as setting the period correctly but there is no way for me to set discountable or metadata on the added invoice item
Creating the setup fee ahead of time using invoiceItems.create and an explicit period and then updating the subscription with billing_cycle_anchor: 'now'. But by the time the subscription is created, a few seconds may have passed so the period on the setup fee item doesn't match that of the subscription. Setting proration_date only affects the proration item but not the new subscription item

#

Thanks @spark berry! So I think subscription schedules have the same limitation because add_invoice_items doesn't allow setting metadata or discountable https://stripe.com/docs/api/subscription_schedules/create#create_subscription_schedule-phases-add_invoice_items

spark berry Sep 9, 2022, 2:24 AM

#

gimme a while to understand your requirements

#

isn't the setup fee item a one time fee?

golden crane Sep 9, 2022, 2:27 AM

#

yeah - use case is we're upselling the customer to a more expensive plan with a new one time setup fee

spark berry Sep 9, 2022, 2:28 AM

#

where are you seeing that the period on the setup fee item doesn't match that of the subscription?

#

since it's a one time fee, i'm a bit confused over what period you're seeing that doesn't match that of the subscription

golden crane Sep 9, 2022, 2:28 AM

#

it does if I use add_invoice_items. but if I manually add the item to the customer using invoiceItems.create then the period needs to be set explicitly

#

i.e., I add the invoice item as a pending item to the customer and when I update the subscription, that pending item gets slurped up into the next invoice

spark berry Sep 9, 2022, 2:31 AM

#

do you have an example request where you get the error that the period needs to be explicitly set? cause this is an optional parameter

golden crane Sep 9, 2022, 2:32 AM

#

oh it's optional but if I don't set it it's just auto set to the request time

spark berry Sep 9, 2022, 2:35 AM

#

then is that period visible to the customer anywhere on their invoice?

#

if the period isn't visible to the customer, and if you're not using the period to implement any logic, i don't think you need to worry about it

golden crane Sep 9, 2022, 2:37 AM

#

it's not so much what the customer sees as the value that gets set on invoice items - we sync the data via Stripe Data Pipeline, etc and use it for accounting purposes

spark berry Sep 9, 2022, 2:37 AM

#

but if you want it to match everything exactly - you could always set the period start and end when creating the invoice item

golden crane Sep 9, 2022, 2:38 AM

#

yeah - that's what I'm trying to do, but the issue is I can set the exact time when creating the item, but not when updating the subscription with a new billing cycle anchor timestamp

#

so it's off by a few seconds depending on latency and that causes some data integrity checks to go off on our end since ideally it'd all be exact

spark berry Sep 9, 2022, 2:43 AM

#

hmmm let me quickly test something

golden crane Sep 9, 2022, 2:44 AM

#

thanks!

spark berry Sep 9, 2022, 3:14 AM

#

sorry about the delay, had to step away to handle something urgent

#

so what i'd suggest is to still use Subscription Schedules. After the invoice is generated (and still in draft mode) invoice.created event, you can still update the invoice item to set discountable=false, and set the metadata. Stripe waits approximately one hour before finalizing the invoice and attempting payment, or sending an email.

golden crane Sep 9, 2022, 3:42 AM

#

np, thanks for the suggestion. we're also using this pay_immediately flag (from a legacy Avalara integration) so that also gives access to the same behavior

#

the only downside is it's a bit clunky since we have to iterate over the invoice later to find the items of interest, create an anonymous product for the fee (since the description is custom), archive it, etc so it's not particularly elegant

#

in the ideal world, add_invoice_items would be more fully featured so we could specify metadata, discountable, and for price_data to have product_data inside of it

#

though I left some feedback here #dev-help message

twin sand Sep 9, 2022, 3:47 AM

#

👋 stepping in and thanks for the feedback. I think my colleague has reported it

golden crane Sep 9, 2022, 3:49 AM

#

thanks! also one thing I noticed with schedules is they don't support setting pending_invoice_item_interval?

twin sand Sep 9, 2022, 3:55 AM

#

Yes as far as I can tell, unfortunately

golden crane Sep 9, 2022, 3:57 AM

#

thanks for confirming - would like to submit a feature request for this so we don't need to manage that out of band

#oleg-codaio-update_subscription