{"id":13483939,"url":"https://github.com/andrewculver/koudoku","last_synced_at":"2025-03-27T15:30:45.186Z","repository":{"id":48831921,"uuid":"7336554","full_name":"andrewculver/koudoku","owner":"andrewculver","description":"Robust subscription support for Rails with Stripe.","archived":false,"fork":false,"pushed_at":"2021-01-04T18:59:44.000Z","size":229,"stargazers_count":1162,"open_issues_count":72,"forks_count":186,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-03-26T11:48:14.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewculver.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-12-27T06:01:59.000Z","updated_at":"2025-02-21T07:15:40.000Z","dependencies_parsed_at":"2022-09-13T17:51:26.688Z","dependency_job_id":null,"html_url":"https://github.com/andrewculver/koudoku","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewculver%2Fkoudoku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewculver%2Fkoudoku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewculver%2Fkoudoku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewculver%2Fkoudoku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewculver","download_url":"https://codeload.github.com/andrewculver/koudoku/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245871694,"owners_count":20686249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:17.101Z","updated_at":"2025-03-27T15:30:44.131Z","avatar_url":"https://github.com/andrewculver.png","language":"Ruby","funding_links":[],"categories":["E-Commerce and Payments","Ruby"],"sub_categories":[],"readme":"# Koudoku\n\n[![Gem Version](https://badge.fury.io/rb/koudoku.png)](https://rubygems.org/gems/koudoku) [![Code Climate](https://codeclimate.com/github/andrewculver/koudoku.png)](https://codeclimate.com/github/andrewculver/koudoku) [![Build Status](https://travis-ci.org/andrewculver/koudoku.png)](https://travis-ci.org/andrewculver/koudoku)\n\nRobust subscription support for Ruby on Rails apps using [Stripe](https://stripe.com), including out-of-the-box pricing pages, payment pages, and  subscription management for your customers. Also makes it easy to manage logic related to new subscriptions, upgrades, downgrades, cancellations, payment failures, and streamlines hooking up notifications, metrics logging, etc.\n\nTo see an example of Koudoku in action, please visit [Koudoku.org](http://koudoku.org/).\n\n\u003csmall\u003e\u003ca href=\"http://churnbuster.io\"\u003e\u003cimg src=\"https://s3.amazonaws.com/andrew-culver-images/churn-buster/koudoku-readme.png\" width=\"196\" height=\"38\" alt=\"Churn Buster\" /\u003e\u003c/a\u003e\u003cbr\u003eKoudoku is authored and maintained by [Andrew Culver](http://twitter.com/andrewculver) and [Christoph Engelhardt](https://twitter.com/itengelhardt). If you find it useful, consider checking out [Churn Buster](http://churnbuster.io). It's designed to help you handle the pain points you'll run into when doing payments at scale.\u003c/small\u003e\n\n## Installation\n\nInclude the following in your `Gemfile`:\n\n```ruby\n    gem 'koudoku'\n```    \n\nAfter running `bundle install`, you can run a Rails generator to do the rest. Before installing, the model you'd like to have own subscriptions must already exist. (In many cases this will be `user`. It may also be something like `company`, etc.)\n\n```ruby\n    rails g koudoku:install user\n    rake db:migrate\n```\n    \nAdd the following to `app/views/layouts/application.html.erb` before your `\u003chead\u003e` tag closes:\n\n```ruby\n    \u003c%= yield :koudoku %\u003e\n```\n    \n(This allows us to inject a Stripe `\u003cscript\u003e` tag in the correct place. If you don't, the payment form will not work.)\n  \nAfter installing, you'll need to add some subscription plans. (You can see an explanation of each of the attributes in the table below.)\n\n**Note:** You need to create the plans in your [Stripe Dashboard](https://dashboard.stripe.com) separately. \n\n```ruby\n    Plan.create({\n      name: 'Personal',\n      price: 10.00,\n      interval: 'month',\n      stripe_id: '1',\n      features: ['1 Project', '1 Page', '1 User', '1 Organization'].join(\"\\n\\n\"),\n      display_order: 1\n    })\n\n    Plan.create({\n      name: 'Team',\n      highlight: true, # This highlights the plan on the pricing page.\n      price: 30.00,\n      interval: 'month',\n      stripe_id: '2',\n      features: ['3 Projects', '3 Pages', '3 Users', '3 Organizations'].join(\"\\n\\n\"),\n      display_order: 2\n    })\n    \n    Plan.create({\n      name: 'Enterprise',\n      price: 100.00, \n      interval: 'month',\n      stripe_id: '3', \n      features: ['10 Projects', '10 Pages', '10 Users', '10 Organizations'].join(\"\\n\\n\"), \n      display_order: 3\n    })\n```    \n\nTo help you understand the attributes:\n    \n| Attribute       | Type    | Function |\n| --------------- | ------- | -------- |\n| `name`          | string  | Name for the plan to be presented to customers. |\n| `price`         | float   | Price per billing cycle. |\n| `interval`      | string  | *Optional.* What is the billing cycle? Valid options are `month`, `year`, `week`, `3-month`, `6-month`. Defaults to `month`. |\n| `stripe_id`     | string  | The Plan ID in Stripe. |\n| `features`      | string  | A list of features. Supports Markdown syntax. |\n| `display_order` | integer | Order in which to display plans. |\n| `highlight`     | boolean | *Optional.* Whether to highlight the plan on the pricing page. |\n\nThe only view installed locally into your app by default is the `koudoku/subscriptions/_social_proof.html.erb` partial which is displayed alongside the pricing table. It's designed as a placeholder where you can provide quotes about your product from customers that could positively influence your visitors.\n    \n### Configuring Stripe API Keys\n\nYou can supply your publishable and secret API keys in `config/initializers/koudoku.rb`. However, by default it will use the `STRIPE_PUBLISHABLE_KEY` and `STRIPE_SECRET_KEY` shell environment variables. This encourages people to keep these API keys out of version control. You may want to rename these environment variables to be more application specific.\n\nIn a bash shell, you can set them in `~/.bash_profile` like so:\n\n```bash\n    export STRIPE_PUBLISHABLE_KEY=pk_0CJwDH9sdh98f79FDHDOjdiOxQob0\n    export STRIPE_SECRET_KEY=sk_0CJwFDIUshdfh97JDJOjZ5OIDjOCH\n```\n    \n(Reload your terminal for these settings to take effect.)\n    \nOn Heroku you accomplish this same effect with [Config Vars](https://devcenter.heroku.com/articles/config-vars):\n\n```bash\n    heroku config:add STRIPE_PUBLISHABLE_KEY=pk_0CJwDH9sdh98f79FDHDOjdiOxQob0\n    heroku config:add STRIPE_SECRET_KEY=sk_0CJwFDIUshdfh97JDJOjZ5OIDjOCH\n```    \n\n## User-Facing Subscription Management\n\nBy default a `pricing_path` route is defined which you can link to in order to show visitors a pricing table. If a user is signed in, this pricing table will take into account their current plan. For example, you can link to this page like so:\n\n```ruby\n    \u003c%= link_to 'Pricing', main_app.pricing_path %\u003e\n```   \n   \n(Note: Koudoku uses the application layout, so it's important that application paths referenced in that layout are prefixed with \"`main_app.`\" like you see above or Rails will try to look the paths up in the Koudoku engine instead of your application.)\n\nExisting users can view available plans, select a plan, enter credit card details, review their subscription, change plans, and cancel at the following route:\n\n```ruby\n    koudoku.owner_subscriptions_path(@user)\n```\n\nIn these paths, `owner` refers to `User` by default, or whatever model has been configured to be the owner of the `Subscription` model.\n\nA number of views are provided by default. To customize the views, use the following generator:\n\n```ruby\n    rails g koudoku:views\n```\n\n### Pricing Table\n\nKoudoku ships with a stock pricing table. By default it depends on Twitter Bootstrap, but also has some additional styles required. In order to import these styles, add the following to your `app/assets/stylesheets/application.css`:\n\n```css\n    *= require 'koudoku/pricing-table'\n```  \n  \nOr, if you've replaced your `application.css` with an `application.scss` (like I always do):\n\n```css\n    @import \"koudoku/pricing-table\"\n``` \n   \n## Using Coupons\n\nWhile more robust coupon support is expected in the future, the simple way to use a coupon is to first create it:\n\n```ruby\n    coupon = Coupon.create(code: '30-days-free', free_trial_length: 30)\n```   \n   \nThen assign it to a _new_ subscription before saving:\n\n```ruby\n    subscription = Subscription.new(...)\n    subscription.coupon = coupon\n    subscription.save\n```    \n\nIt should be noted that these coupons are different from the coupons provided natively by Stripe.\n    \n## Implementing Logging, Notifications, etc.\n\nThe included module defines the following empty \"template methods\" which you're able to provide an implementation for in `Subscription`:\n\n - `prepare_for_plan_change`\n - `prepare_for_new_subscription`\n - `prepare_for_upgrade`\n - `prepare_for_downgrade`\n - `prepare_for_cancelation`\n - `prepare_for_card_update`\n - `finalize_plan_change!`\n - `finalize_new_subscription!`\n - `finalize_upgrade!`\n - `finalize_downgrade!`\n - `finalize_cancelation!`\n - `finalize_card_update!`\n - `card_was_declined`\n \nBe sure to include a call to `super` in each of your implementations, especially if you're using multiple concerns to break all this logic into smaller pieces.\n\nBetween `prepare_for_*` and `finalize_*`, so far I've used `finalize_*` almost exclusively. The difference is that `prepare_for_*` runs before we settle things with Stripe, and `finalize_*` runs after everything is settled in Stripe. For that reason, please be sure not to implement anything in `finalize_*` implementations that might cause issues with ActiveRecord saving the updated state of the subscription.\n\n### Webhooks\n\nWe use [stripe_event](https://github.com/integrallis/stripe_event) under the hood to support webhooks.\nThe default webhooks URL is `/koudoku/webhooks`.\n\nYou can add your own webhooks using the (reduced) stripe_event syntax in the `config/initializers/koudoku.rb` file: \n\n```\n# /config/initializers/koudoku.rb\nKoudoku.setup do |config|\n  config.subscriptions_owned_by = :user\n  config.stripe_publishable_key = ENV['STRIPE_PUBLISHABLE_KEY']\n  config.stripe_secret_key = ENV['STRIPE_SECRET_KEY']\n  \n  # add webhooks\n  config.subscribe 'charge.failed', YourChargeFailed\nend\n\n``` \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewculver%2Fkoudoku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewculver%2Fkoudoku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewculver%2Fkoudoku/lists"}