{"id":13835621,"url":"https://github.com/solidusio/solidus_subscriptions","last_synced_at":"2025-05-16T14:02:55.401Z","repository":{"id":15212629,"uuid":"76986147","full_name":"solidusio/solidus_subscriptions","owner":"solidusio","description":"An extension to add subscriptions to your Solidus store.","archived":false,"fork":false,"pushed_at":"2025-02-21T16:42:11.000Z","size":1282,"stargazers_count":50,"open_issues_count":26,"forks_count":55,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-05-11T06:05:59.610Z","etag":null,"topics":["ecommerce","extensions","hacktoberfest","solidus","subscriptions"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solidusio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"solidus"}},"created_at":"2016-12-20T19:37:32.000Z","updated_at":"2025-02-13T13:58:46.000Z","dependencies_parsed_at":"2024-02-24T19:51:27.778Z","dependency_job_id":"337e4927-0610-4030-9add-56ad2af9383a","html_url":"https://github.com/solidusio/solidus_subscriptions","commit_stats":{"total_commits":661,"total_committers":41,"mean_commits":"16.121951219512194","dds":0.62178517397882,"last_synced_commit":"1149f416b1be2a854296a0802adad94f1f92b067"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_subscriptions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_subscriptions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_subscriptions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_subscriptions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solidusio","download_url":"https://codeload.github.com/solidusio/solidus_subscriptions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301422,"owners_count":22047901,"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":["ecommerce","extensions","hacktoberfest","solidus","subscriptions"],"created_at":"2024-08-04T14:01:06.549Z","updated_at":"2025-05-16T14:02:55.355Z","avatar_url":"https://github.com/solidusio.png","language":"Ruby","readme":"# solidus_subscriptions\n\n[![Test](https://github.com/solidusio/solidus_subscriptions/actions/workflows/test.yml/badge.svg)](https://github.com/solidusio/solidus_subscriptions/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/solidusio/solidus_subscriptions/branch/main/graph/badge.svg)](https://codecov.io/gh/solidusio/solidus_subscriptions)\n\nA Solidus extension to add subscriptions to your store.\n\n## Installation\n\nAdd solidus_subscriptions to your Gemfile:\n\n```ruby\ngem 'solidus_subscriptions', github: 'solidusio/solidus_subscriptions'\n```\n\n### Starter Frontend\n\nBundle your dependencies and run the installation generator:\n\n```shell\n$ bundle\n$ bin/rails generate solidus_subscriptions:install\n```\n\nPlease, be aware that the installation only works with the default\nimplementation of the starter frontend. Any customization to the files that\nwill be modified by the installer might break the installation procedure.\nIf that happens, try to adapt the installed code on top of the customizations\nof the store.\n\n### Legacy Frontend\n\nIf you are using the legacy `solidus_frontend` gem, please run this command instead:\n\n```shell\n$ bin/rails generate solidus_subscriptions:install --frontend=classic\n```\n\n### Guest checkout\n\nSubscriptions require a user to be present to allow them to be managed after they are purchased.\n\nBecause of this, you must disable guest checkout for orders which contain `subscription_line_items`.\n\nAn example would be adding this to the registration page:\n\n```erb\n\u003c%# spree/checkout/registration.html.erb %\u003e\n\u003c% if Spree::Config[:allow_guest_checkout] \u0026\u0026 current_order.subscription_line_items.empty? %\u003e\n```\n\nThis allows guests to add subscriptions to their carts as guests, but forces them to login or create\nan account before purchasing them.\n\n## Usage\n\n### Purchasing subscriptions\n\nBy default, only Spree::Variants can be subscribed to. To subscribe to a variant, it must have the\n`subscribable` attribute set to true.\n\nTo subscribe to a variant, include the following parameters when posting to `/orders/populate`:\n\n```json5\n{\n  // other add to cart params\n  subscription_line_item: {\n    quantity: 2,             // number of units in each subscription order\n    subscribable_id: 1234,   // which variant the subscription is for\n    interval_length: 1,      // time between subscription activations\n    interval_units: \"month\", // plural qualifier for length (day/week/month/year)\n    end_date: '2011/12/13'   // stop processing after this date (use null to process ad nauseam)\n  }\n}\n```\n\nThis will associate a `SolidusSubscriptions::LineItem` to the line item being added to the cart.\n\nThe customer will not be charged for the subscription until it is processed. The subscription line\nitems should be shown to the user on the cart page by looping over\n`Spree::Order#subscription_line_items`.\n\nWhen the order is finalized, a `SolidusSubscriptions::Subscription` will be created for each group\nof subscription line items which can be fulfilled by a single subscription.\n\n#### Example\n\nAn order is finalized and has the following associated subscription line items:\n\n1. `{ subscribable_id: 1, interval_length: 1, interval_units: \"month\" }`\n2. `{ subscribable_id: 2, interval_length: 1, interval_units: \"month\" }`\n3. `{ subscribable_id: 1, interval_length: 2, interval_units: \"month\" }`\n\nThis will generate 2 subscriptions: the first related to subscription line items 1 and 2, and the\nsecond related to subscription line item 3.\n\n### Processing subscriptions\n\nTo process actionable subscriptions simply run:\n\n```bash\n$ bundle exec rake solidus_subscriptions:process\n```\n\nThe task creates ActiveJob jobs which can be fulfilled by your queue library of choice.\n\nWe suggest using the [Whenever](https://github.com/javan/whenever) gem to schedule the task.\n\n### Promotion rules\n\nThis extensions adds the following [Promotion rules](https://guides.solidus.io/developers/promotions/promotion-rules.html):\n* `SolidusSubscriptions::Promotion::Rules::SubscriptionCreationOrder` which applies if the order is creating a subscription;\n* `SolidusSubscriptions::Promotion::Rules::SubscriptionInstallmentOrder` which applies if the order is an installment of a subscription.\n\n### Churn Buster integration\n\nThis extension optionally integrates with [Churn Buster](https://churnbuster.io) for failed payment\nrecovery. In order to enable the integration, simply add your Churn Buster credentials to your\nconfiguration:\n\n```ruby\nSolidusSubscriptions.configure do |config|\n  # ...\n\n  config.churn_buster_account_id = 'YOUR_CHURN_BUSTER_ACCOUNT_ID'\n  config.churn_buster_api_key = 'YOUR_CHURN_BUSTER_API_KEY'\nend\n```\n\nThe extension will take care of reporting successful/failed payments and payment method changes\nto Churn Buster.\n\n### Failed installments retries\n\nThe extension generates an installment for each subscription cycle, however some of them can fail\n(e.g. for an expired credit card). On each processor run the extension will try to complete all past\nfailed installments, however this is not always the desired behaviour.\n\nIf you want to process only the latest installment in each subscription, regardless of any number of\nfailed installments prior to that, you can configure the extension like so:\n\n```ruby\nSolidusSubscriptions.configure do |config|\n  # ...\n\n  config.clear_past_installments = true\nend\n```\n\n### Minimum cancellation notice\n\nThe minimum cancellation notice is set to 0 days by default - users can cancel their subscription whenever they like. To change this, you can configure the extension like this:\n\n```ruby\nSolidusSubscriptions.configure do |config|\n  # ...\n\n  config.minimum_cancellation_notice = 10.days\nend\n```\n\n### Subscription product deletion\nWhen a product is soft deleted, its subscription line items need to be deleted as well, in order to avoid error on subscription processing.\nIf the product class is `Spree::Variant`, this corner case is handled automatically on the variant soft deletion, otherwise it should be handled manually.\n\n## Development\n\n### Testing the extension\n\nFirst bundle your dependencies, then run `bin/rake`. `bin/rake` will default to building the dummy\napp if it does not exist, then it will run specs. The dummy app can be regenerated by using\n`bin/rake extension:test_app`.\n\n```shell\nbin/rake\n```\n\nTo run [Rubocop](https://github.com/bbatsov/rubocop) static code analysis run\n\n```shell\nbundle exec rubocop\n```\n\nWhen testing your application's integration with this extension you may use its factories.\nSimply add this require statement to your spec_helper:\n\n```ruby\nrequire 'solidus_subscriptions/factories'\n```\n\n### Running the sandbox\n\nTo run this extension in a sandboxed Solidus application, you can run `bin/sandbox`. The path for\nthe sandbox app is `./sandbox` and `bin/rails` will forward any Rails commands to\n`sandbox/bin/rails`.\n\nHere's an example:\n\n```\n$ bin/rails server\n=\u003e Booting Puma\n=\u003e Rails 6.0.2.1 application starting in development\n* Listening on tcp://127.0.0.1:3000\nUse Ctrl-C to stop\n```\n\n### Updating the changelog\n\nBefore and after releases the changelog should be updated to reflect the up-to-date status of\nthe project:\n\n```shell\nbin/rake changelog\ngit add CHANGELOG.md\ngit commit -m \"Update the changelog\"\n```\n\n### Releasing new versions\n\nYour new extension version can be released using `gem-release` like this:\n\n```shell\nbundle exec gem bump -v 1.6.0\nbin/rake changelog\ngit commit -a --amend\ngit push\nbundle exec gem release\n```\n\n## License\n\nCopyright (c) 2016 Stembolt, released under the New BSD License\n\nOriginally sponsored by [Goby](https://www.goby.co).\n","funding_links":["https://opencollective.com/solidus"],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio%2Fsolidus_subscriptions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolidusio%2Fsolidus_subscriptions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio%2Fsolidus_subscriptions/lists"}