5 ms·

Stripe. Their docs are amazing too, I always find it a pleasure integrating their API. https://stripe.com/docs/api https://stripe.com/docs/api

by sc00ty 10y ago

jxm262 10y ago
^ Came in to say this. I use Stripe for inspiration on their API, docs, and even the general UI/UX to get a feel for something simple yet elegant.
- mrgalaxy 10y ago
  Jeez, glad I'm not the only who feels Stripe's API is basically the golden standard when it comes to a properly implemented REST API and documentation.
jdc0589 10y ago
nit picking devil's advocate: not all of the API is documented. There are some features that exists, but you have to know about. Granted, this is intentional. e.g.: "billing_cycle_anchor" in the subscription API.
iLoch 10y ago
+1 for Stripe. BlockScore is another one similar to Stripe in terms of docs and intuitive design.
madelinecameron 10y ago
Nooooooooo. I dislike Stripe's API. There are parts of it that just make no sense. Say, you want to set a billing date for that fancy subscription. Yeah, just set a trial date until the billing date you want. Oh, and don't forget to charge a prorated difference (by hand, with charges)! Want to upgrade that subscription? Yeah, cancel that subscription and start a new one. Oh, and don't forget to set that trial again! Want to cancel that subscription but not until their next billing date? Hahaha, yeah no. You need to cancel now through Stripe and set up a process to cancel on your side. (Not the biggest complaint, but really. If I am having Stripe manage my subscriptions, they should do it all) And I am sure there are many other details which would also drive me mad. With all of that said, I think Stripe's API is definitely one of the better ones since my complaints are more functionality / feature requests than complaints about how it is set up.
- leesalminen 10y ago
  I agree. Their subscription functionality is half-baked. We're 2 years into using Stripe for subscription management and it's such a hassle to move anywhere else that we keep hobbling along with it. My advice when starting a SaaS company: think through your subscription software early on, before it's a headache to even think about migrating away.
- encoderer 10y ago
  So you want to set a billing date and then charge a pro-rated amount that first month? And what do you mean "upgrade"? You can move from one plan to the next and charges are pro-rated automatically for you. I, too, loath the amount of time we've spent on subscription/billing but I'm just surprised that none of the issues you've listed are really causing any pain for us.
- guayosr 10y ago
  (I work at Stripe.) Although it’s kind of proving your point that the API could be easier to use/better documented, here are some simpler ways to do what you’re looking for: * Upgrading a plan (no cancellation needed): https://stripe.com/docs/api#update_subscription-plan https://stripe.com/docs/api#update_subscription-plan > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d plan={new_plan}` * Canceling a subscription at the end of the billing cycle (no need to handle on your end): https://stripe.com/docs/api#update_subscription-at_period_end https://stripe.com/docs/api#update_subscription-at_period_en... > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -X DELETE -d at_period_end=true` * Anchoring subscription to a date (sorry! :( , this is undocumented but should be out soon): https://stripe.com/docs/api#create_subscription https://stripe.com/docs/api#create_subscription > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d billing_cycle_anchor={timestamp}` That said, agreed overall that our subscriptions support needs some love. We're starting to spend more time on exactly this, so would love any feedback you (or anyone else reading) are willing to share. I'm eduardo@stripe.com.
  - hoodoof 10y ago
    Is this in an obvious place in the docs or in an FAQ?
bparanj 10y ago
-1 for Stripe. The API is designed without any thought how the use cases need to use it. Leaks the JSON structure of the document to the client. This breaks your code when they change the JSON structure.
- kornish 10y ago
  Well, all code depending on JSON presumably breaks when that JSON changes. That's what versioning is for. What do you mean by "Leaks the JSON structure of the document to the client"?
- nfm 10y ago
  I'm not sure what you mean about changing the JSON structure; the Stripe API is versioned and you have to opt-in to any updates, including breaking changes like removing or renaming keys in the response.
joshmn 10y ago
+0. Some parts are great, other parts not so much. My thoughts echo the other's here.
BlackjackCF 10y ago
I feel like their API isn't super uniform in a lot of the ways it's integrated, but I will give them a +1 for allowing very easy versioning.
ciq_steve 10y ago
Even better is the realtime support on their IRC channel.
tlogan 10y ago
Sadly, Stripe API is not so great :( It seems like the API is way too complex to do certain operations. Especially some very common use cases: for example, how to apply discount for next year for customers who already have subscription (we wanted to emulate how Comcast always gives you discount if you want cancel and took us weeks to make that working ...). I think they do want to fix all these issues but API is not designed to be easily expandable. It's actually very hard to find a decent REST API :( My points here are the following: 1. Think very very hard about how people will use your API <-- this is critical. This also includes operational characteristics of your API (performances, how often it is going to be called, optimization, etc.) 2. Make API easily expendable. Especially relationships between models. Sometimes, it is ok (or even better) just to organize it as "SQL wrapper". Like SOQL by Salesforce - but that again depends on number 1.

Stripe. Their docs are amazing too, I always find it a pleasure integrating their API. https://stripe.com/docs/api https://stripe.com/docs/api

by sc00ty 10y ago

Stripe. Their docs are amazing too, I always find it a pleasure integrating their API. https://stripe.com/docs/api https://stripe.com/docs/api

jxm262 10y ago

^ Came in to say this. I use Stripe for inspiration on their API, docs, and even the general UI/UX to get a feel for something simple yet elegant.

mrgalaxy 10y ago
Jeez, glad I'm not the only who feels Stripe's API is basically the golden standard when it comes to a properly implemented REST API and documentation.

jdc0589 10y ago

nit picking devil's advocate: not all of the API is documented. There are some features that exists, but you have to know about. Granted, this is intentional. e.g.: "billing_cycle_anchor" in the subscription API.

iLoch 10y ago

+1 for Stripe. BlockScore is another one similar to Stripe in terms of docs and intuitive design.

madelinecameron 10y ago

Nooooooooo. I dislike Stripe's API. There are parts of it that just make no sense. Say, you want to set a billing date for that fancy subscription. Yeah, just set a trial date until the billing date you want. Oh, and don't forget to charge a prorated difference (by hand, with charges)! Want to upgrade that subscription? Yeah, cancel that subscription and start a new one. Oh, and don't forget to set that trial again! Want to cancel that subscription but not until their next billing date? Hahaha, yeah no. You need to cancel now through Stripe and set up a process to cancel on your side. (Not the biggest complaint, but really. If I am having Stripe manage my subscriptions, they should do it all) And I am sure there are many other details which would also drive me mad. With all of that said, I think Stripe's API is definitely one of the better ones since my complaints are more functionality / feature requests than complaints about how it is set up.

leesalminen 10y ago
I agree. Their subscription functionality is half-baked. We're 2 years into using Stripe for subscription management and it's such a hassle to move anywhere else that we keep hobbling along with it. My advice when starting a SaaS company: think through your subscription software early on, before it's a headache to even think about migrating away.
encoderer 10y ago
So you want to set a billing date and then charge a pro-rated amount that first month? And what do you mean "upgrade"? You can move from one plan to the next and charges are pro-rated automatically for you. I, too, loath the amount of time we've spent on subscription/billing but I'm just surprised that none of the issues you've listed are really causing any pain for us.
guayosr 10y ago
(I work at Stripe.) Although it’s kind of proving your point that the API could be easier to use/better documented, here are some simpler ways to do what you’re looking for: * Upgrading a plan (no cancellation needed): https://stripe.com/docs/api#update_subscription-plan https://stripe.com/docs/api#update_subscription-plan > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d plan={new_plan}` * Canceling a subscription at the end of the billing cycle (no need to handle on your end): https://stripe.com/docs/api#update_subscription-at_period_end https://stripe.com/docs/api#update_subscription-at_period_en... > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -X DELETE -d at_period_end=true` * Anchoring subscription to a date (sorry! :( , this is undocumented but should be out soon): https://stripe.com/docs/api#create_subscription https://stripe.com/docs/api#create_subscription > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d billing_cycle_anchor={timestamp}` That said, agreed overall that our subscriptions support needs some love. We're starting to spend more time on exactly this, so would love any feedback you (or anyone else reading) are willing to share. I'm eduardo@stripe.com.
- hoodoof 10y ago
  Is this in an obvious place in the docs or in an FAQ?

bparanj 10y ago

-1 for Stripe. The API is designed without any thought how the use cases need to use it. Leaks the JSON structure of the document to the client. This breaks your code when they change the JSON structure.

kornish 10y ago
Well, all code depending on JSON presumably breaks when that JSON changes. That's what versioning is for. What do you mean by "Leaks the JSON structure of the document to the client"?
nfm 10y ago
I'm not sure what you mean about changing the JSON structure; the Stripe API is versioned and you have to opt-in to any updates, including breaking changes like removing or renaming keys in the response.

joshmn 10y ago

+0. Some parts are great, other parts not so much. My thoughts echo the other's here.

BlackjackCF 10y ago

I feel like their API isn't super uniform in a lot of the ways it's integrated, but I will give them a +1 for allowing very easy versioning.

ciq_steve 10y ago

Even better is the realtime support on their IRC channel.

tlogan 10y ago

Sadly, Stripe API is not so great :( It seems like the API is way too complex to do certain operations. Especially some very common use cases: for example, how to apply discount for next year for customers who already have subscription (we wanted to emulate how Comcast always gives you discount if you want cancel and took us weeks to make that working ...). I think they do want to fix all these issues but API is not designed to be easily expandable. It's actually very hard to find a decent REST API :( My points here are the following: 1. Think very very hard about how people will use your API <-- this is critical. This also includes operational characteristics of your API (performances, how often it is going to be called, optimization, etc.) 2. Make API easily expendable. Especially relationships between models. Sometimes, it is ok (or even better) just to organize it as "SQL wrapper". Like SOQL by Salesforce - but that again depends on number 1.