{"id":23765810,"url":"https://github.com/solidusio-contrib/solidus_easypost","last_synced_at":"2025-04-05T22:05:24.790Z","repository":{"id":5410320,"uuid":"53078294","full_name":"solidusio-contrib/solidus_easypost","owner":"solidusio-contrib","description":":envelope: Solidus integration with EasyPost.","archived":false,"fork":false,"pushed_at":"2025-02-08T10:17:50.000Z","size":356,"stargazers_count":14,"open_issues_count":14,"forks_count":26,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-29T21:04:04.003Z","etag":null,"topics":["ecommerce","ecommerce-platform","shipping","shipping-methods","solidus","solidus-easypost","solidus-extensions"],"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-contrib.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}},"created_at":"2016-03-03T19:46:53.000Z","updated_at":"2025-01-11T08:50:58.000Z","dependencies_parsed_at":"2025-02-08T10:18:34.045Z","dependency_job_id":"3a00f863-0b58-4aa3-b9d0-c305965ae0d2","html_url":"https://github.com/solidusio-contrib/solidus_easypost","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_easypost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_easypost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_easypost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_easypost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solidusio-contrib","download_url":"https://codeload.github.com/solidusio-contrib/solidus_easypost/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406085,"owners_count":20933803,"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","ecommerce-platform","shipping","shipping-methods","solidus","solidus-easypost","solidus-extensions"],"created_at":"2024-12-31T23:17:56.228Z","updated_at":"2025-04-05T22:05:24.775Z","avatar_url":"https://github.com/solidusio-contrib.png","language":"Ruby","readme":"# solidus_easypost\n\n\n\nThis is an extension to integrate EasyPost with Solidus.\n\nDue to how it works, you will not be able to use any other extension for shipping methods. Your own\nshipping methods will not work, either. But the good thing is that you won't have to worry about\nthat, because EasyPost handles it all for you.\n\nYou will need to [sign up for an account](https://www.easypost.com/) to use this extension.\n\n## Installation\n\nAdd solidus_easypost to your Gemfile:\n\n```ruby\ngem 'solidus_easypost'\n```\n\nBundle your dependencies and run the installation generator:\n\n```shell\nbin/rails generate solidus_easypost:install\n```\n\nThis will create an initializer at `config/initializers/solidus_easypost.rb`. Read through the\navailable configuration options and make sure to adjust the extension for your requirements.\n\nFinally, you will need to configure Solidus to use the EasyPost stock estimator:\n\n```ruby\n# config/initializers/spree.rb\nSpree.config do |config|\n  config.stock.estimator_class = 'SolidusEasypost::Estimator'\nend\n```\n\n## Usage\n\nOnce you switch to the EasyPost rate calculator, the extension will start calculating shipping rates\nfor all shipments. The cheapest rate will be selected by default, but your users will be able to\nchange the selected rate in the `delivery` step of the checkout process, if they wish.\n\nAdmins will also be able to download the postage label associated to each EasyPost shipment after\na shipment has been bought.\n\n### Buying labels upon shipping\n\nBy default, the extension also adds a callback to the `ship` event on the `Spree::Shipment` model,\nautomatically buying the selected rate from EasyPost.\n\nIf you want to disable this logic, you can set `purchase_labels` to `false`.\n\n### Customizing shipping rate calculation\n\nBy default, the extension will pass the entire cost of shipping to the user (i.e., the shipping cost\npresented to the user will be equal to the rate received from the EasyPost API).\n\nIf you want to override this logic (e.g., you want to offer your users free shipping, but still buy\nthe rates from EasyPost), you can provide your own `shipping_rate_calculator_class`.\n\n### Customizing shipping method selection\n\nBy default, the extension will create shipping methods for each type of carrier/service for which it\nreceives a rate from the EasyPost API. These are not available to users by default, and must be\nenabled before they are visible and selectable in the storefront during the checkout process.\n\nIf you want to override this logic, you can provide your own `shipping_method_selector_class`.\n\n### Customizing parcel dimension calculator\n\nBy default, the extension will use the default weight dimension calculator to calculate the parcel dimension that is passed to EasyPost. The default calculator uses the variants weight to calculate the parcel weight without taking into consideration the other package properties like `width`, `height`, and `lenght`.\n\nIf you want to override this logic, you can provide your own `parcel_dimension_calculator_class`.\n\n### Tracking cartons via EasyPost\n\nYou can optionally track packages via EasyPost's [Trackers API](https://www.easypost.com/docs/api#trackers).\nIn order to do this, you can call the `#easypost_tracker` method on any carton:\n\n```ruby\ncarton = Spree::Carton.find(2)\ncarton.easypost_tracker # =\u003e #\u003cEasypost::Tracker\u003e\n```\n\nThis will also save the ID of the tracker on the `easy_post_tracker_id` column, to more easily\nretrieve the tracker in the future.\n\n\u003e NOTE: In orders for carton tracking to work, you need to make sure that the `tracking` column\n\u003e in `spree_cartons` contains a valid tracking number, and that the `carrier` column in\n\u003e `spree_shipping_methods` contains a carrier name [that EasyPost will recognize](https://www.easypost.com/docs/api#carrier-tracking-strings).\n\u003e The extension already generates compliant shipping methods by default, but you may need to change\n\u003e the data on your custom shipping methods if you want to track them.\n\nYou can also enable automatic tracking for all created cartons:\n\n```ruby\nSolidusEasypost.configure do |config|\n  config.track_all_cartons = true\nend\n```\n\n### Getting tracking updates via webhooks\n\nOnce a tracker has been created for a given carton, you can either use it manually or you can use\nEasyPost's [webhooks](https://www.easypost.com/docs/api#webhooks) to have any shipping updates\nforwarded to your application.\n\nIn order for webhooks to work, you need to install the [solidus_webhooks](https://github.com/solidusio-contrib/solidus_webhooks)\nextension. When the extension is available, a webhook will be automatically configured at\n`/webhooks/easypost_trackers`. Simply add it to your EasyPost dashboard with the following\nconfiguration:\n\n- *Environment:* `Production` or `Test`\n- *Webhook URL:* `https://your-store.com/webhooks/easypost_trackers?token=[YOUR_TOKEN]` (replace`[YOUR_TOKEN]` with the API key of an admin user or, better yet, a[webhook user](https://github.com/solidusio-contrib/solidus_webhooks#restricting-permissions)\n\nNow, when Solidus gets a tracking update from EasyPost, a `solidus_easypost.tracker.updated` event\nwill be fired. The event's payload will contain the `:carton` and `:payload` keys, with the\n`Spree::Carton` object associated to the tracker and the EasyPost payload respectively.\n\n### Customizing the tracking webhook handler\n\nIf you want to override default webhook handler, you can provide your own `webhook_handler_class` in your configuration.\n\nNote that, if you override the webhook handler, no events will be fired out of the box.\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_easypost/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) 2015 Brendan Deere, released under the New BSD License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio-contrib%2Fsolidus_easypost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolidusio-contrib%2Fsolidus_easypost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio-contrib%2Fsolidus_easypost/lists"}