Discounts applied during trial periods

[Michael Dobbins]

In order to support some custom per-seat pricing, we apply a coupon for a fixed amount off (not percentage) at the time that a user subscribes to a plan. The problem is that a discount is being applied to customers' accounts when they sign up for a plan that has a free trial period. When the customers get billed the first time (after trial has expired), an additional credit is applied to their starting balance. This means that the customers will receive a discount twice the amount of the coupon the first time they are billed. Please note that we are using Stripe version 1.8.3, using the php library. How/when can I apply a coupon to a customer subscription so that they don't get twice the amount off?

Here is an example: A Customer signs up for an annual plan with a 14 day free trial. The cost of the membership is $500, and a $225 coupon is applied to the customer subscription at the time the subscription is created. Customer is charged for the first time after the free trial has ended, and the discount of $225 is applied. In addition, the customer has a starting balance of $225 (for the coupon applied during the trial period). That means the customer only gets charged $50 instead of $275 (500 - 225 - 225 = 50).

I did not expect this. The solution I came up with was to subscribe the customer to the plan without applying the coupon at time of subscription created. Then I would wait for the customer.subscription.updated webhook event and apply the coupon to the subscription , if the previous status was 'trialing' and the new status is 'active'. However, I don't think this will work, since the customer should already have been invoiced when customer.subscription.updated event fires. I also thought about zeroing out the customer balance on invoice.created event, but I will not be able to tell definitively WHY the customer has a starting balance (was a credit issued in the dashboard?).

How do you recommend we contend with this issue? I did not realize the customer balance would be credited for coupons applied during the trial period. If there were a way to specify the date on which a discount should start, then we could set the coupon to be applied at the end of the trial. I am not sure the best way to handle it. Any advice would be greatly appreciated.

Mike

[Jim Danz]

Hey Michael,

Thanks for writing in to clarify this.

We actually considered this (the fact that discounts could lead to account credits) to be a bug, and fixed if in October. The catch is that in case anyone was relying on the old behavior, we put it behind an API gate:

https://stripe.com/docs/upgrades#2013-10-29

So if you upgrade your API version to 2013-10-29 or newer, you should no longer see this behavior for new coupons.  (Note that thus won't change how old coupons behave, but if you have an old coupon that you need fixed up, you can reply directly to me and I can take care of that.)

Let me know if the API version upgrade doesn't do the trick, as such would indicate a regression on our end.

Cheers,

Jim

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at http://groups.google.com/a/lists.stripe.com/group/api-discuss/.

To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss...@lists.stripe.com.

[Michael Dobbins]

Jim,

 

Thanks for the quick response. I will need to upgrade my php client library to the 2013-10-29  version of the API (v1.9.1?). If I can do that, I will send you an email so you can fix the existing coupons. The only thing is, the coupons in question were created in 3rd party Stripe accounts via Stripe Connect. The coupons are created with the API on the fly, based on the plan and quantity chosen, if a coupon for that account/amount off has not already been created.

 

I am not sure what I need to do to upgrade the API version both for my Stripe account and for connected 3rd party accounts, or how I would go about getting coupons for connected Stripe accounts fixed. I assume that when I make my first API call after upgrading my client library, both my Stripe API version my connected accounts' API versions will get updated to the version of the client library. Is this correct, or do I have to upgrade via the Stripe dashboard in all Stripe accounts?

 

It looks like I will need v1.9.1 of the php client library from https://github.com/stripe/stripe-php/releases; I do not want to upgrade to the new version where multiple subscriptions were added (v1.10.1?), since I will have to make additional changes to support the multiple subscriptions per customer.  Also, is there a way to view the API documentation for a previous API version @ https://stripe.com/docs/api?

Thanks,

Mike

[Jim Danz]

Hi Michael,

Oops, sorry for responding quickly at first but then letting this sit.
stripe-php version is pretty well decoupled from API version, in that
stripe-php is willing to send whatever parameters you specify over the
wire, and stripe-php also infers object properties based on the
response that you get over the wire. In general, it should be safe to
upgrade to the latest-and-greatest stripe-php even if you want to keep
your API version as an old version.

Unfortunately, there isn't a way to view documentation for previous
API versions. We haven't done the required over time to differentiate
between bug fixes / changing mistakes in API docs, versus documenting
new features. With that being said, we'd be more than happy to answer
any particular questions that you have about old API versions (the
summaries of changes are always available at
https://stripe.com/docs/upgrades).

Also, as a general point about versioning
(https://stripe.com/docs/api#versioning): when processing a request,
by default we use the API version that you have set on your account.
However, when you can set the API version specifically in your client
libraries, eg in PHP:
Stripe::setApiVersion("2013-10-29");
This will cause the library to send a Stripe-Version header over the
wire, overriding the default API version of your account

In terms of how API versioning plays with connect, we definitely bias
in favor of the connect application owner here. Plenty of connect
application users simply create Stripe accounts and connect them to
apps, making none of their own API requests, etc. Also, we want to
make sure that as a connect application owner, you experience unified
behavior across your connected merchants. So -- as a Connect
application *owner*, when you set your API version on your account,
this will apply to all requests that you make, even those that you are
making *on behalf of* your connected users. The same goes for using
Stripe::setApiVersion in PHP -- this works for requests made as your
own merchant, and also for requests that you are making on behalf of
your connected users. I hope I'm understanding your question there
and that that clarifies.

Cheers,
Jim

[Michael Dobbins]

Jim,

Thanks for getting back to me. I discovered the Stripe::setApiVersion()
method yesterday, and made some changes to my code to set the api
version when my class is instantiated.

As for coupons that were created on behalf of connected stripe accounts,
how would I go about getting those coupons 'updated' so that their
customers do not receive double coupons after a trial period?

Thanks,

Mike

[Amber Feng]

Hi Michael,

If you email sup...@stripe.com with a list of the coupon IDs, we're
happy to update them for you!

Amber