spree_easypost 6.0.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad5ff952bf4c6793d867e260b9061c3e19a9efbd5e4383a4bcf0d2522f387ee0
+  data.tar.gz: c5c0c74919b84867fa54e8c9b4e56bda8e7e9fe6c2fb7f90e5d5792ac4c61f4e
+SHA512:
+  metadata.gz: d65fa05b70d3a3b933cf6a9f46275ba1e02022c58e0e18cb3a0b2db587d1299f644fe0e22b79122bc78554a93122de7fcfcbab4257a85b17b1fc598ce3871fef
+  data.tar.gz: 720dfa79747c360ef893c9b860d0283e6869c91d65f20a102a0e383d085177ffac0df68de3c110243d02c79c18961f5257cc7c4c77f3c2ebc76b250b0b78e6bd

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, Vendo Sp. z o.o., Vendo Connect Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,39 @@
+# spree_easypost
+
+Live multi-carrier delivery rates for Spree via [EasyPost](https://www.easypost.com) — the reference implementation of the `Spree::DeliveryRateProvider` interface, built on the official [`easypost`](https://github.com/EasyPost/easypost-ruby) Ruby SDK.
+
+## What it does
+
+- **`SpreeEasyPost::Integration`** holds the store's EasyPost API key (a masked `:password` preference), managed from the dashboard's Settings → Integrations page. The key decides the mode — EasyPost issues separate test and production keys.
+- **`SpreeEasyPost::DeliveryRateProvider`** quotes live at checkout. One delivery method is the carrier connection: every service EasyPost returns for the address becomes its own named rate ("UPS Ground", "USPS Priority Mail", …) carrying the carrier, service level and estimated delivery date. The method's service rows optionally narrow which services are offered, rename them, or add a markup per service; with no rows, everything EasyPost returns is offered and the method-level markup applies. One EasyPost API call per package, however many services come back.
+- **`SpreeEasyPost::FulfillmentProvider`** buys the label when a fulfillment ships — the rate quoted at checkout when still valid, otherwise a fresh quote bought only for the exact carrier service the customer selected. Tracking lands on the fulfillment, the label is served via `documents`, and cancelling files a refund request. A purchase failure never blocks shipping — it is reported and the admin buys the label manually.
+
+## Setup
+
+1. Add the gem: `bundle add spree_easypost`
+2. In the admin dashboard, open **Settings → Integrations**, connect **EasyPost**, and activate it (activation verifies the key against the EasyPost API).
+3. Create ONE delivery method (**Settings → Delivery methods**) with **EasyPost** as its rate and fulfillment provider. The service picker lists what your EasyPost account can actually quote — read from a throwaway quote rather than the carrier-accounts endpoint, which is production-only and reports no service levels. That's enough — customers see every service EasyPost quotes. Optionally narrow the offered services, rename them ("UPS 1 day"), or add a handling-fee markup, per service or method-wide.
+
+Methods without the EasyPost provider keep pricing through their calculator — the two coexist freely per store.
+
+## Notes
+
+- Weights are converted to ounces from the store's unit system (imperial → pounds, metric → grams).
+- The gallery card's logo is the official hosted EasyPost asset (`logo_url` — no asset pipeline involved; the dashboard falls back to a letter avatar if unreachable) and its description lives in `config/locales/`, resolved per the store's locale.
+
+## Testing
+
+```bash
+cd spree/providers/easypost
+bundle install
+bundle exec rake test_app
+bundle exec rspec
+```
+
+The suite runs offline: unit specs stub the client, and the API-contract specs replay recorded HTTP through VCR (`spec/vcr/`). To re-record the cassettes against the live EasyPost test API, delete them and run the suite with `EASYPOST_TEST_API_KEY` set — the key is filtered out of recordings.
+
+For a quick live sanity check outside the suite:
+
+```bash
+EASYPOST_TEST_API_KEY=EZTK... bin/smoke
+```

data/Rakefile

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rspec/core/rake_task'
+require 'spree/testing_support/common_rake'
+
+RSpec::Core::RakeTask.new
+
+task default: :spec
+
+desc "Generates a dummy app for testing"
+task :test_app do
+  ENV['LIB_NAME'] = 'spree_easypost'
+  Rake::Task['common:test_app'].invoke
+end

data/app/models/spree_easypost/delivery_rate_provider.rb

@@ -0,0 +1,135 @@
+module SpreeEasyPost
+  # Quotes a delivery method from EasyPost. One method is the carrier
+  # connection: every service EasyPost returns for the address becomes its
+  # own rate ("UPS Ground", "USPS Priority", ...), and the method's service
+  # rows narrow, rename or mark up individual services. Methods sharing this
+  # provider within a request reuse one shipment-create API call.
+  class DeliveryRateProvider < Spree::DeliveryRateProvider::Base
+    def self.integration_class
+      'SpreeEasyPost::Integration'
+    end
+
+    def self.provider_name
+      SpreeEasyPost::PROVIDER_NAME
+    end
+
+    # EasyPost quotes real parcel shipments, so it only prices methods that
+    # ship to an address.
+    def self.requires_address?
+      true
+    end
+
+    # Domestic destination + nominal parcel for the service-listing probe
+    # quote; never charged, nothing to clean up.
+    PROBE_DESTINATION = {
+      street1: '179 N Harbor Dr',
+      city: 'Redondo Beach',
+      state: 'CA',
+      zip: '90277',
+      country: 'US',
+      name: 'Service catalog probe'
+    }.freeze
+    PROBE_OUNCES = 16
+
+    # The carrier services this account can actually sell.
+    #
+    # Read from a throwaway quote rather than the carrier-accounts endpoint:
+    # the latter is production-only (a test key is rejected outright), while
+    # a quote works on both key tiers and reports carrier names exactly as
+    # they arrive on real rates — which is what service rows must match.
+    # Costs one API call, made only when an admin opens the picker.
+    def self.service_catalog(integration)
+      return Spree::DeliveryRateProvider::ServiceCatalog.none if integration.nil?
+
+      shipment = integration.client.shipment.create(
+        from_address: SpreeEasyPost::Integration::VERIFICATION_ADDRESS,
+        to_address: PROBE_DESTINATION,
+        parcel: { weight: PROBE_OUNCES }
+      )
+      Spree::DeliveryRateProvider::ServiceCatalog.listing(services_from(shipment.rates))
+    rescue StandardError => e
+      Spree::DeliveryRateProvider::ServiceCatalog.unavailable(e.message)
+    end
+
+    # One entry per (carrier, service) the probe quoted, deduplicated and
+    # ordered for a stable picker.
+    def self.services_from(rates)
+      rates.map { |rate| [rate.carrier, rate.service] }.uniq.sort.map do |carrier, service|
+        { carrier: carrier, service: service, label: "#{carrier} #{service.to_s.titleize}" }
+      end
+    end
+    private_class_method :services_from
+
+    # A rating failure must never break checkout: any API error suppresses
+    # this method (the customer still sees calculator-priced options) and is
+    # reported for observability rather than raised into the rate refresh.
+    #
+    # @param package [Spree::Stock::Package]
+    # @return [Array<Spree::DeliveryRateProvider::Estimate>]
+    def estimates(package)
+      return [] if integration.nil?
+      return [] if package.owner&.ship_address.nil?
+
+      shipment = begin
+        easypost_shipment(package)
+      rescue StandardError => e
+        Rails.error.report(e, context: { delivery_method_id: delivery_method.id }, source: 'spree_easypost.rating')
+        nil
+      end
+      return [] if shipment.nil?
+
+      rates = Array(shipment.rates)
+      log_rating_failures(shipment) if rates.empty?
+
+      rates.map do |rate|
+        Spree::DeliveryRateProvider::Estimate.new(
+          cost: rate.rate,
+          currency: rate.currency,
+          carrier: rate.carrier,
+          service_level: rate.service,
+          estimated_delivery_date: rate.delivery_date,
+          metadata: { 'easypost_rate_id' => rate.id, 'easypost_shipment_id' => rate.shipment_id }
+        )
+      end
+    end
+
+    private
+
+    # EasyPost answers 201 with an empty rate list and per-carrier rate_error
+    # messages when it cannot quote (incomplete origin address, unsupported
+    # lane, oversize parcel). Without surfacing them, the method silently
+    # vanishing from checkout is undiagnosable from the outside.
+    def log_rating_failures(shipment)
+      # The carrier account is part of the identity: the same carrier can fail
+      # differently per linked account, and deduplicating on carrier alone
+      # would hide one of them.
+      reasons = Array(shipment.messages).map do |message|
+        carrier = [message.carrier, message.try(:carrier_account_id)].compact.join('/')
+        "#{carrier}: #{message.message}"
+      end.uniq
+      reasons = ['no rates returned and no carrier messages given'] if reasons.empty?
+
+      Rails.logger.warn(
+        "[SpreeEasyPost] no rates for delivery method '#{delivery_method.name}' " \
+        "(shipment #{shipment.id}): #{reasons.join(' | ')}"
+      )
+    end
+
+    # One shipment-create returns rates for every carrier and service, so all
+    # delivery methods sharing this provider within a request reuse it.
+    def easypost_shipment(package)
+      cache_key = [:easypost_shipment, store.id, package.stock_location.id, package.owner.id]
+      Spree::Current.provider_cache[cache_key] ||= integration.client.shipment.create(
+        **shipment_params(package)
+      )
+    end
+
+    # Built by the shared helper so a label bought against this quote carries
+    # exactly the customs form and duty terms the quote was priced with.
+    def shipment_params(package)
+      SpreeEasyPost.shipment_params(
+        package, package.stock_location, package.owner.ship_address, integration, store
+      )
+    end
+  end
+end

data/app/models/spree_easypost/fulfillment_provider.rb

@@ -0,0 +1,305 @@
+module SpreeEasyPost
+  # Buys and refunds EasyPost labels for outbound parcels and returns
+  # (docs/plans/6.0-shipping-labels-and-deliveries.md). Core records what
+  # was bought as a Spree::ShippingLabel and never asks twice for a parcel
+  # that already holds one, so nothing here remembers a purchase — the label
+  # row does.
+  #
+  # Nothing here may raise: a purchase failure is reported and answered with
+  # nil, which the explicit buy-label step surfaces as a 422 and the one-click
+  # fulfill degrades to "no label yet".
+  class FulfillmentProvider < Spree::FulfillmentProvider::Base
+    # EasyPost carrier names → Spree.tracking_carriers keys, so a bought label
+    # gets the same badge and tracking page a hand-entered number would.
+    CARRIER_KEYS = {
+      'USPS' => 'usps',
+      'UPS' => 'ups',
+      'FedEx' => 'fedex',
+      'FedExDefault' => 'fedex',
+      'DHLExpress' => 'dhl',
+      'DhlEcs' => 'dhl',
+      'DPD' => 'dpd',
+      'GLS' => 'gls',
+      'RoyalMail' => 'royal_mail',
+      'CanadaPost' => 'canada_post',
+      'AustraliaPost' => 'australia_post'
+    }.freeze
+
+    LABEL_FORMATS = {
+      'application/pdf' => 'pdf',
+      'image/png' => 'png',
+      'application/zpl' => 'zpl',
+      'text/plain' => 'zpl'
+    }.freeze
+
+    def self.integration_class
+      'SpreeEasyPost::Integration'
+    end
+
+    def self.provider_name
+      SpreeEasyPost::PROVIDER_NAME
+    end
+
+    def self.generates_labels?
+      true
+    end
+
+    # An outbound parcel buys the rate quoted at checkout when it is still
+    # valid; EasyPost quotes expire, so a stale or missing quote is re-quoted
+    # from the actual fulfillment and bought only when a rate for the exact
+    # carrier/service the customer selected comes back — silently shipping a
+    # different service than the customer paid for is worse than no label.
+    #
+    # A return buys an inbound shipment from the address the order shipped
+    # to back to the return's stock location, at the cheapest rate the
+    # account offers: return postage is the merchant's own money and no
+    # service was ever chosen for it.
+    #
+    # @param owner [Spree::Fulfillment, Spree::Return]
+    # @return [Spree::LabelPurchase, nil]
+    def purchase_label(owner)
+      integration = integration_for(owner)
+      return if integration.nil?
+
+      shipment =
+        if owner.is_a?(Spree::Return)
+          buy_return(integration, owner)
+        else
+          buy_quoted(integration, owner) || requote_and_buy(integration, owner)
+        end
+      return if shipment.nil?
+
+      label_purchase(shipment)
+    rescue EasyPost::Errors::EasyPostError => e
+      # EasyPost says exactly what is wrong — an incomplete origin address, an
+      # unserviceable destination — and the merchant is the only one who can
+      # fix it. Passed through rather than reported as a connection problem.
+      report(e, owner)
+      raise Spree::Core::LabelPurchaseRefused, e.message
+    rescue Spree::Core::LabelPurchaseRefused
+      # Already the merchant's answer, raised by name from further in. It is a
+      # StandardError, so without this it would be swallowed as nil below and
+      # the buy would fail with no reason given.
+      raise
+    rescue StandardError => e
+      report(e, owner)
+      nil
+    end
+
+    # Files the refund with EasyPost. USPS refunds settle later and come
+    # back as `submitted`; commercial carriers usually answer at once.
+    #
+    # @param shipping_label [Spree::ShippingLabel]
+    # @return [String, false]
+    def refund_label(shipping_label)
+      # The account that sold the label, not whichever one the parcel's
+      # current method points at — a rerouted parcel still owes its postage
+      # back to the carrier it was bought from.
+      integration = shipping_label.integration || integration_for(shipping_label.owner)
+      return false if integration.nil? || shipping_label.external_id.blank?
+
+      shipment = integration.client.shipment.refund(shipping_label.external_id)
+      refund_outcome(shipment.try(:refund_status))
+    rescue EasyPost::Errors::EasyPostError => e
+      # A parcel already in the carrier's hands, a label too old to void:
+      # EasyPost says which, and only the merchant can act on it.
+      report(e, shipping_label.owner)
+      raise Spree::Core::LabelRefundRefused, e.message
+    rescue StandardError => e
+      report(e, shipping_label.owner)
+      false
+    end
+
+    # Dispatch is the label; there is nothing else to tell EasyPost.
+    def create_fulfillment(_fulfillment)
+      {}
+    end
+
+    def cancel_fulfillment(_fulfillment)
+      true
+    end
+
+    # The tracker page EasyPost hosts for the delivery's label.
+    #
+    # @param delivery [Spree::Delivery]
+    # @return [String, nil]
+    def tracking_url(delivery)
+      delivery&.shipping_label&.metadata&.dig('easypost_tracker_url')
+    end
+
+    # Customs forms and commercial invoices the purchase produced. The label
+    # itself is the Spree::ShippingLabel, never listed here.
+    #
+    # @param owner [Spree::Fulfillment, Spree::Return]
+    # @return [Array<Spree::ShippingDocument>]
+    def documents(owner)
+      # Read from the loaded association rather than re-scoping it: this is
+      # called once per parcel while serializing an order, and a fresh query
+      # each time defeats the controller's preload.
+      label = owner.shipping_labels.detect { |candidate| !candidate.refunded? }
+      forms = label&.metadata&.dig('easypost_forms')
+      Array(forms).filter_map do |form|
+        next if form['url'].blank?
+
+        Spree::ShippingDocument.new(kind: form['form_type'].presence || 'form', url: form['url'])
+      end
+    end
+
+    private
+
+    def buy_quoted(integration, fulfillment)
+      quoted = fulfillment.selected_delivery_rate&.metadata || {}
+      shipment_id = quoted['easypost_shipment_id']
+      rate_id = quoted['easypost_rate_id']
+      return if shipment_id.blank? || rate_id.blank?
+
+      buy(integration, fulfillment.stock_location, fulfillment.store, shipment_id, rate_id)
+    rescue EasyPost::Errors::EasyPostError
+      nil
+    end
+
+    def requote_and_buy(integration, fulfillment)
+      # The selected rate carries the carrier service the customer chose —
+      # the delivery method no longer pins one (it offers many).
+      selected = fulfillment.selected_delivery_rate
+      address = fulfillment.address || fulfillment.order&.ship_address
+
+      # Each of these is the merchant's to fix, so each says so rather than
+      # failing as "check the carrier connection".
+      raise Spree::Core::LabelPurchaseRefused, Spree.t('easypost.errors.no_destination') if address.nil?
+
+      if selected&.carrier.blank? || selected.service_level.blank?
+        raise Spree::Core::LabelPurchaseRefused, Spree.t('easypost.errors.rate_not_quoted')
+      end
+
+      shipment = integration.client.shipment.create(
+        **SpreeEasyPost.shipment_params(
+          fulfillment.to_package, fulfillment.stock_location, address, integration, fulfillment.store
+        )
+      )
+      rate = shipment.rates.find do |candidate|
+        candidate.carrier == selected.carrier && candidate.service == selected.service_level
+      end
+
+      # Silently buying a different service than the customer paid for is
+      # worse than no label, so this refuses and names the service.
+      if rate.nil?
+        raise Spree::Core::LabelPurchaseRefused,
+              Spree.t('easypost.errors.service_unavailable', service: "#{selected.carrier} #{selected.service_level}")
+      end
+
+      buy(integration, fulfillment.stock_location, fulfillment.store, shipment.id, rate.id)
+    end
+
+    def buy_return(integration, return_record)
+      address = return_record.ship_from_address
+      return if address.nil? || return_record.stock_location.nil?
+
+      params = SpreeEasyPost.shipment_params(
+        return_record.to_package, address, return_record.stock_location, integration, return_record.store
+      )
+      shipment = integration.client.shipment.create(**params, is_return: true)
+      rate = EasyPost::Util.get_lowest_object_rate(shipment)
+      return if rate.nil?
+
+      buy(integration, return_record.stock_location, return_record.store, shipment.id, rate.id)
+    end
+
+    # Labels bought on EasyPost's own carrier accounts (USPS) require an
+    # EndShipper — the legally responsible shipping party. Created fresh per
+    # purchase so it always matches the current warehouse address; label buys
+    # are rare enough that caching one would only buy staleness.
+    def buy(integration, stock_location, store, shipment_id, rate_id)
+      buy_params = { rate: { id: rate_id } }
+      end_shipper_id = end_shipper_id(integration, stock_location, store)
+      buy_params[:end_shipper_id] = end_shipper_id if end_shipper_id.present?
+
+      integration.client.shipment.buy(shipment_id, **buy_params)
+    end
+
+    # Both ways this can fail are the merchant's to fix, so both say what to
+    # fix and where. Buying without an end shipper was the alternative, and a
+    # carrier that requires one answers that with a bare "malformed syntax"
+    # naming no field at all.
+    # Whatever the warehouse can supply is sent and EasyPost judges it: what
+    # it requires here is its rule to change, and a local copy of that list
+    # would quietly disagree with the real one the first time it moved. Its
+    # answer names the field ("Phone number is empty"), which is what the
+    # merchant needs, so it is passed through with the location that owns it.
+    def end_shipper_id(integration, stock_location, store)
+      params = SpreeEasyPost.end_shipper_params(stock_location, store)
+      return if params.nil?
+
+      integration.client.end_shipper.create(**params).id
+    rescue EasyPost::Errors::EasyPostError => e
+      report(e, stock_location)
+      raise Spree::Core::LabelPurchaseRefused,
+            Spree.t('easypost.errors.origin_address_refused',
+                    location: location_name(stock_location), reason: carrier_reason(e))
+    end
+
+    # EasyPost's summary line is often generic ("Missing required parameter")
+    # while the field it means sits in the errors array, so the detail is
+    # preferred and the summary is the fallback.
+    def carrier_reason(error)
+      details = Array(error.try(:errors)).filter_map do |detail|
+        next detail if detail.is_a?(String)
+
+        field = detail['field'].to_s.split('.').last
+        [field.presence&.humanize, detail['message']].compact_blank.join(' ')
+      end
+
+      details.compact_blank.presence&.to_sentence || error.message
+    end
+
+    def location_name(stock_location)
+      stock_location.try(:name).presence || stock_location.try(:address1)
+    end
+
+    def label_purchase(shipment)
+      rate = shipment.try(:selected_rate)
+      postage_label = shipment.try(:postage_label)
+      tracker = shipment.try(:tracker)
+
+      Spree::LabelPurchase.new(
+        external_id: shipment.id,
+        carrier: carrier_key(rate&.carrier),
+        service: rate&.service,
+        tracking_number: shipment.tracking_code,
+        tracking_url: tracker&.public_url,
+        cost: rate&.rate.to_d,
+        currency: rate&.currency,
+        format: LABEL_FORMATS[postage_label&.label_file_type.to_s],
+        file_url: postage_label&.label_url,
+        metadata: {
+          'easypost_tracker_id' => tracker&.id,
+          'easypost_tracker_url' => tracker&.public_url,
+          'easypost_rate_id' => rate&.id,
+          'easypost_forms' => Array(shipment.try(:forms)).map { |form| { 'form_type' => form.try(:form_type), 'url' => form.try(:form_url) } }
+        }.compact
+      )
+    end
+
+    def carrier_key(carrier)
+      return if carrier.blank?
+
+      CARRIER_KEYS[carrier.to_s] || carrier.to_s
+    end
+
+    def refund_outcome(refund_status)
+      case refund_status.to_s
+      when 'refunded' then 'refunded'
+      when 'rejected', 'not_applicable' then false
+      else 'refund_requested'
+      end
+    end
+
+    def report(error, subject)
+      Rails.error.report(
+        error,
+        context: { subject_type: subject.class.name, subject_id: subject.try(:id) },
+        source: 'spree_easypost.fulfillment'
+      )
+    end
+  end
+end

data/app/models/spree_easypost/integration.rb

@@ -0,0 +1,98 @@
+module SpreeEasyPost
+  # Per-store EasyPost credentials. The API key decides the mode — EasyPost
+  # issues separate test and production keys, so there is no mode toggle.
+  class Integration < Spree::Integration
+    # EasyPost rejects any other value outright, and a rejected shipment
+    # create is a checkout with no delivery options at all.
+    INCOTERMS = %w[CFR CIF CIP CPT DAT DAP DDP EXW FAS FCA FOB].freeze
+    # EasyPost's contents enum minus `other`, which additionally demands a
+    # free-text explanation nothing here supplies — offering it would only
+    # produce a rejected declaration.
+    CUSTOMS_CONTENTS_TYPES = %w[documents gift merchandise returned_goods sample dangerous_goods humanitarian_donation].freeze
+
+    # Declared credentials first: they are the two an operator must supply,
+    # and the form renders in this order.
+    preference :api_key, :password
+    # The shared secret configured on the EasyPost webhook; signs every
+    # delivery. Without it webhooks are refused — an unauthenticated report
+    # could otherwise mark parcels delivered, which starts return windows.
+    preference :webhook_secret, :password
+
+    # Customs declaration defaults, used only on international labels. The
+    # signer takes legal responsibility for the declared contents, so it names
+    # a person at the merchant rather than the store.
+    preference :customs_signer, :string
+    preference :customs_contents_type, :string, default: 'merchandise', in: CUSTOMS_CONTENTS_TYPES
+    # Who pays duties and taxes on arrival. Defaults to DAP — the recipient is
+    # billed by the carrier. DDP bills the merchant instead, so only choose it
+    # once duties are actually collected from the customer at checkout;
+    # otherwise the merchant absorbs them silently.
+    preference :incoterm, :string, default: 'DAP', in: INCOTERMS
+
+    validates :preferred_incoterm, inclusion: { in: INCOTERMS }, allow_blank: true
+    validates :preferred_customs_contents_type, inclusion: { in: CUSTOMS_CONTENTS_TYPES }, allow_blank: true
+
+    # EasyPost's own documentation example address — used only to prove the
+    # key authenticates.
+    VERIFICATION_ADDRESS = {
+      street1: '417 Montgomery Street',
+      city: 'San Francisco',
+      state: 'CA',
+      zip: '94104',
+      country: 'US'
+    }.freeze
+
+    def self.integration_group
+      'shipping'
+    end
+
+    # Verifies the EasyPost HMAC signature and translates `tracker.updated`
+    # payloads into UpdateTracking arguments. Non-tracker events (batches,
+    # refund confirmations) return nil and are acknowledged without action.
+    def parse_webhook_event(raw_post, headers)
+      raise Spree::Integration::WebhookSignatureError, 'webhook secret not configured' if preferred_webhook_secret.blank?
+
+      payload = EasyPost::Util.validate_webhook(raw_post, headers, preferred_webhook_secret)
+
+      SpreeEasyPost::TrackerEvent.from_webhook(payload)&.to_update_tracking_arguments
+    rescue EasyPost::Errors::SignatureVerificationError => e
+      raise Spree::Integration::WebhookSignatureError, e.message
+    end
+
+    def self.integration_name
+      SpreeEasyPost::PROVIDER_NAME
+    end
+
+    def self.logo_url
+      'https://www.easypost.com/wp-content/uploads/2026/03/EasyPost-Logo.svg'
+    end
+
+    # Fallback for hosts without the gem's translations; the localized
+    # description in config/locales wins.
+    def self.description
+      'Live multi-carrier delivery rates at checkout through your EasyPost account.'
+    end
+
+    # Verifies the key by creating an address — the one authenticated call
+    # that works in both modes. Account-management endpoints
+    # (`carrier_account.all`, `api_key.all`) are production-only and reject a
+    # valid test key with "This resource requires a production API Key",
+    # which would block merchants from connecting a test key at all.
+    # Addresses are inert: no shipment, no charge, nothing to clean up.
+    #
+    # Rescues broadly, not just SDK errors — a DNS failure or timeout must
+    # surface as a clean activation error, never a 500.
+    def can_connect?
+      client.address.create(VERIFICATION_ADDRESS)
+      true
+    rescue StandardError => e
+      self.connection_error_message = e.message
+      false
+    end
+
+    # @return [EasyPost::Client]
+    def client
+      @client ||= EasyPost::Client.new(api_key: preferred_api_key)
+    end
+  end
+end

data/app/models/spree_easypost/tracker_event.rb

@@ -0,0 +1,84 @@
+module SpreeEasyPost
+  # One `tracker.updated` webhook, translated into the vocabulary
+  # Spree::Deliveries::UpdateTracking speaks.
+  #
+  # Translating carrier status names is the provider's job precisely so core
+  # never learns any one carrier's spelling — EasyPost's own vocabulary happens
+  # to be close, but `unknown` and `error` are not the same thing to us, and a
+  # future provider's will not line up at all.
+  class TrackerEvent
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    # EasyPost status → Spree tracking status. Anything unlisted is recorded as
+    # `unknown` rather than dropped: a merchant looking at a parcel wants to
+    # see that something was reported, even if we cannot name it.
+    STATUS_MAP = {
+      'pre_transit' => 'pre_transit',
+      'in_transit' => 'in_transit',
+      'out_for_delivery' => 'out_for_delivery',
+      'available_for_pickup' => 'available_for_pickup',
+      'delivered' => 'delivered',
+      'return_to_sender' => 'return_to_sender',
+      'failure' => 'failure',
+      'cancelled' => 'failure',
+      'error' => 'failure',
+      'unknown' => 'unknown'
+    }.freeze
+
+    attribute :tracking_code, :string
+    attribute :status, :string
+    attribute :estimated_delivery_at, :datetime
+    attribute :delivered_at, :datetime
+    attr_accessor :details
+
+    # @param payload [Hash] the webhook body EasyPost posted
+    # @return [SpreeEasyPost::TrackerEvent, nil] nil when the payload is not a
+    #   tracker update or carries no tracking code to match on
+    def self.from_webhook(payload)
+      # Always a plain Hash: the integration hands over what the SDK's
+      # signature validation parsed from the raw body.
+      payload = payload.to_h.deep_stringify_keys
+      return unless payload['description'].to_s.start_with?('tracker.')
+
+      tracker = payload['result'] || {}
+      tracking_code = tracker['tracking_code']
+      return if tracking_code.blank?
+
+      new(
+        tracking_code: tracking_code,
+        status: STATUS_MAP.fetch(tracker['status'].to_s, 'unknown'),
+        estimated_delivery_at: tracker['est_delivery_date'],
+        delivered_at: delivery_time(tracker),
+        details: tracker.slice('status', 'status_detail', 'carrier', 'est_delivery_date', 'public_url')
+      )
+    end
+
+    # The shape {Spree::Deliveries::UpdateTracking} takes, plus the
+    # tracking code the endpoint matches the fulfillment on.
+    #
+    # @return [Hash]
+    def to_update_tracking_arguments
+      {
+        tracking_code: tracking_code,
+        tracking_status: status,
+        estimated_delivery_at: estimated_delivery_at,
+        delivered_at: delivered_at,
+        details: details
+      }
+    end
+
+    # The scan that actually recorded delivery, which is earlier than the
+    # webhook and is what a return window has to run from.
+    def self.delivery_time(tracker)
+      return unless tracker['status'].to_s == 'delivered'
+
+      delivering_scan = Array(tracker['tracking_details']).reverse.find do |detail|
+        detail.is_a?(Hash) && detail['status'].to_s == 'delivered'
+      end
+
+      delivering_scan&.dig('datetime')
+    end
+    private_class_method :delivery_time
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,12 @@
+---
+en:
+  spree:
+    easypost:
+      errors:
+        no_destination: This parcel has no delivery address, so no carrier can quote it.
+        origin_address_refused: "%{location} cannot be used as the shipping origin: %{reason}"
+        rate_not_quoted: This delivery rate was not quoted by EasyPost. Re-quote the fulfillment and pick a carrier service before buying a label.
+        service_unavailable: "%{service} is no longer offered for this parcel. Re-quote the fulfillment and pick another service."
+    integrations:
+      easy_post:
+        description: Live multi-carrier delivery rates at checkout through your EasyPost account, including your own negotiated carrier contracts.

data/lib/spree_easypost/engine.rb

@@ -0,0 +1,47 @@
+require 'rails/engine'
+
+module SpreeEasyPost
+  class Engine < Rails::Engine
+    engine_name 'spree_easypost'
+
+    # Gem name and module disagree on word boundaries (spree_easypost →
+    # SpreeEasyPost, matching the official EasyPost SDK's casing), so
+    # Zeitwerk needs telling once.
+    initializer 'spree_easypost.inflections', before: :set_autoload_paths do
+      Rails.autoloaders.each do |autoloader|
+        autoloader.inflector.inflect('spree_easypost' => 'SpreeEasyPost')
+      end
+    end
+
+    # One line per EasyPost API call in the Rails log, so a checkout that
+    # quotes no rates can be read instead of guessed at. Development only by
+    # default; set SPREE_EASYPOST_HTTP_LOG=1 to turn it on elsewhere. The
+    # request body is deliberately not logged — it carries customer addresses.
+    initializer 'spree_easypost.http_logging' do
+      next unless Rails.env.development? || ENV['SPREE_EASYPOST_HTTP_LOG'].present?
+
+      logger_hook = lambda do |context|
+        duration_ms = ((context.response_timestamp - context.request_timestamp) * 1000).round
+        line = "[EasyPost] #{context.method.to_s.upcase} #{context.path} -> #{context.http_status} (#{duration_ms}ms)"
+
+        if (400..599).cover?(context.http_status.to_i)
+          Rails.logger.warn("#{line} #{context.response_body.to_s.truncate(500)}")
+        else
+          Rails.logger.info(line)
+        end
+      rescue StandardError => e
+        # The SDK invokes hooks inline in the request path with no rescue of
+        # its own — a logging hiccup must never take checkout down with it.
+        Rails.logger.warn("[EasyPost] logging hook failed: #{e.class}: #{e.message}")
+      end
+
+      EasyPost::Hooks.subscribe(:response, :spree_rails_logger, logger_hook)
+    end
+
+    config.after_initialize do
+      Spree.integrations << 'SpreeEasyPost::Integration'
+      Spree.delivery_rate_providers << SpreeEasyPost::DeliveryRateProvider
+      Spree.fulfillment_providers << SpreeEasyPost::FulfillmentProvider
+    end
+  end
+end

data/lib/spree_easypost.rb

@@ -0,0 +1,237 @@
+require 'easypost'
+require 'spree_core'
+require 'spree_easypost/engine'
+
+module SpreeEasyPost
+  # Vendor branding, shared by both providers and the integration.
+  PROVIDER_NAME = 'EasyPost'.freeze
+
+  # EasyPost rejects a parcel weighing zero ("must be greater than 0"), and
+  # products without a weight are ordinary in Spree — so a weightless package
+  # is quoted at this nominal ounce rather than failing the whole request.
+  # Rates come back slightly low for such carts, which is the better failure:
+  # the alternative is no delivery options at all.
+  MINIMUM_OUNCES = 0.1
+
+  # EasyPost expects parcel dimensions in inches. A package reports its
+  # dimensions in the unit the store's system implies, so the conversion is
+  # from there — through the one conversion table Spree has, rather than a
+  # second copy of the same constants.
+  #
+  # @param value [Numeric, nil]
+  # @param store [Spree::Store, nil]
+  # @return [Float]
+  def self.inches(value, store)
+    from = Spree::Variant.store_dimensions_unit(store)
+
+    Spree::Measurement.convert_length(value, from: from, to: 'in').to_f.round(2)
+  end
+
+  # EasyPost expects parcel weight in ounces. A package reports its weight in
+  # the store's weight unit, which is a separate setting from its unit
+  # system — a metric store may still weigh in pounds.
+  #
+  # @param weight [Numeric, nil]
+  # @param store [Spree::Store, nil]
+  # @return [Float]
+  def self.ounces(weight, store)
+    from = store&.preferred_weight_unit.presence || Spree::Measurement::DEFAULT_WEIGHT_UNIT
+    converted = Spree::Measurement.convert_weight(weight, from: from, to: 'oz').to_f.round(2)
+
+    [converted, MINIMUM_OUNCES].max
+  end
+
+  # EasyPost parcel payload for a package: weight always, dimensions when
+  # the store configured a default package — carriers bill dimensional
+  # weight above size thresholds, so a weight-only parcel under-quotes
+  # bulky-but-light shipments.
+  #
+  # @param package [Spree::Stock::Package]
+  # @param store [Spree::Store, nil]
+  # @return [Hash]
+  def self.parcel_params(package, store)
+    params = { weight: ounces(package.weight, store) }
+
+    dimensions = package.dimensions
+    return params if dimensions.nil?
+
+    params.merge(
+      length: inches(dimensions[:length], store),
+      width: inches(dimensions[:width], store),
+      height: inches(dimensions[:height], store)
+    )
+  end
+
+  # EasyPost address payload from a Spree address or stock location.
+  #
+  # `name`/`company` look optional — rating succeeds without them — but
+  # buying a label fails with "address.name or address.company required",
+  # so both are always sent when the record has them.
+  #
+  # @param source [Spree::Address, Spree::StockLocation]
+  # @return [Hash]
+  def self.address_params(source)
+    {
+      name: address_name(source),
+      company: source.try(:company),
+      street1: source.address1,
+      street2: source.address2,
+      city: source.city,
+      state: source.respond_to?(:state_abbr) ? source.state_abbr : source.state&.abbr,
+      zip: source.zipcode,
+      country: source.country&.iso,
+      phone: source.phone
+    }.compact_blank
+  end
+
+  # Addresses carry a person's name; stock locations carry the location's.
+  def self.address_name(source)
+    return source.full_name if source.respond_to?(:full_name)
+
+    source.try(:name)
+  end
+
+  # US export filings are waived below this declared value (NOEEI 30.37(a));
+  # above it a shipment needs its own filing number, which only the merchant
+  # can supply, so no exemption is claimed on its behalf.
+  EEI_EXEMPTION_LIMIT_USD = 2_500
+
+  # Customs payload for an international shipment. Nil for domestic ones —
+  # EasyPost rejects a customs form on a domestic label, and every carrier
+  # treats "no customs_info" as the domestic case.
+  #
+  # Classification (HS code, country of origin) is sent per item when the
+  # merchant recorded it. It is deliberately not required: carriers differ on
+  # what they demand, and a rejected label carries the carrier's own message,
+  # which is more actionable than a guess made here.
+  #
+  # The declaration is only certified when the integration names a signer:
+  # EasyPost requires one whenever `customs_certify` is set, so certifying
+  # without it would fail every international quote for an integration that
+  # never configured a signer — the common case.
+  #
+  # @param package [Spree::Stock::Package]
+  # @param origin [Spree::StockLocation, nil] where the parcel ships from
+  # @param destination [Spree::Address, nil] where it is going
+  # @param integration [SpreeEasyPost::Integration, nil] customs signer/contents preferences
+  # @return [Hash, nil] nil when the shipment is domestic or undeterminable
+  def self.customs_info_params(package, origin, destination, integration = nil)
+    return unless international?(origin, destination)
+
+    items = customs_items_params(package)
+    return if items.empty?
+
+    signer = integration&.preferred_customs_signer.presence
+    params = {
+      contents_type: integration&.preferred_customs_contents_type.presence || 'merchandise',
+      restriction_type: 'none',
+      eel_pfc: eel_pfc_for(items, origin),
+      customs_items: items
+    }
+    params[:customs_certify] = true if signer
+    params[:customs_signer] = signer
+    params.compact_blank
+  end
+
+  # The full shipment-create payload, shared by quoting and label purchase so
+  # the two can never diverge. Whatever is set here at quote time is what a
+  # label bought against that quote carries — including the customs form and
+  # the duty terms, which are shipment properties EasyPost fixes at creation
+  # and does not accept on the buy call.
+  #
+  # @param package [Spree::Stock::Package]
+  # @param origin [Spree::StockLocation, nil]
+  # @param destination [Spree::Address, nil]
+  # @param integration [SpreeEasyPost::Integration, nil]
+  # @param store [Spree::Store, nil]
+  # @return [Hash]
+  def self.shipment_params(package, origin, destination, integration, store)
+    params = {
+      from_address: address_params(origin),
+      to_address: address_params(destination),
+      parcel: parcel_params(package, store)
+    }
+
+    customs_info = customs_info_params(package, origin, destination, integration)
+    return params if customs_info.nil?
+
+    params[:customs_info] = customs_info
+    incoterm = integration&.preferred_incoterm.presence
+    params[:options] = { incoterm: incoterm } if incoterm
+    params
+  end
+
+  # The US export exemption, claimed only where it actually applies: a
+  # US-origin shipment declared in US dollars under the filing threshold.
+  # Anything else — a foreign origin, a non-dollar declaration, a value over
+  # the limit — is left for the carrier to require rather than mis-declared
+  # here. The threshold is a dollar figure, so a declaration in another
+  # currency cannot be compared against it without a conversion this code
+  # deliberately does not attempt.
+  #
+  # @param items [Array<Hash>] customs items with :value and :currency
+  # @param origin [Spree::StockLocation, nil]
+  # @return [String, nil]
+  def self.eel_pfc_for(items, origin)
+    return unless origin&.country_code == 'US'
+    return unless items.all? { |item| item[:currency].to_s.upcase == 'USD' }
+
+    declared_value = items.sum { |item| item[:value].to_f }
+    'NOEEI 30.37(a)' if declared_value < EEI_EXEMPTION_LIMIT_USD
+  end
+
+  # One customs item per package line. Quantity, value and weight always;
+  # classification only when present.
+  #
+  # @param package [Spree::Stock::Package]
+  # @return [Array<Hash>]
+  def self.customs_items_params(package)
+    store = package.owner&.store
+
+    package.contents.filter_map do |item|
+      variant = item.variant
+      next if variant.nil?
+
+      {
+        description: variant.customs_description_for_declaration,
+        quantity: item.quantity,
+        value: (item.price.to_f * item.quantity).round(2),
+        weight: ounces(item.weight, store),
+        origin_country: variant.country_of_origin.presence,
+        hs_tariff_number: variant.hs_code.presence,
+        currency: package.owner&.currency
+      }.compact_blank
+    end
+  end
+
+  # A shipment crosses a customs border when its origin and destination
+  # countries differ. Unknown countries mean domestic — never attach a
+  # customs form on a guess.
+  def self.international?(origin, destination)
+    origin_code = origin&.country_code
+    destination_code = destination&.country_code
+    return false if origin_code.blank? || destination_code.blank?
+
+    origin_code != destination_code
+  end
+
+  # EndShipper payload — the party legally responsible for the shipment,
+  # required when buying labels on EasyPost's own carrier accounts (USPS
+  # refuses the purchase without one). Whatever the warehouse and store can
+  # supply is sent as-is: which fields EasyPost demands is its rule, and it
+  # answers a payload it cannot accept by naming the field, which is more
+  # use to a merchant than a list maintained here that would drift out of
+  # step the first time that rule changed.
+  #
+  # @param stock_location [Spree::StockLocation, nil]
+  # @param store [Spree::Store, nil]
+  # @return [Hash, nil] nil only when there is no location to describe
+  def self.end_shipper_params(stock_location, store)
+    return if stock_location.nil?
+
+    address_params(stock_location).merge(
+      phone: stock_location.phone.presence || store&.contact_phone.presence,
+      email: store&.mail_from_address.presence || store&.customer_support_email.presence
+    ).compact_blank
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: spree_easypost
+version: !ruby/object:Gem::Version
+  version: 6.0.0.beta1
+platform: ruby
+authors:
+- Vendo Connect Inc.
+- Vendo Sp. z o.o.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: easypost
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: spree_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 6.0.0.beta1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 6.0.0.beta1
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Live multi-carrier delivery rates for Spree via EasyPost. Generate and
+  buy shipping labels both for fulfillments and returns. Supports 100+ carierrs worldwide.
+email: hello@spreecommerce.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/models/spree_easypost/delivery_rate_provider.rb
+- app/models/spree_easypost/fulfillment_provider.rb
+- app/models/spree_easypost/integration.rb
+- app/models/spree_easypost/tracker_event.rb
+- config/locales/en.yml
+- lib/spree_easypost.rb
+- lib/spree_easypost/engine.rb
+homepage: https://spreecommerce.org
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/spree/spree/issues
+  changelog_uri: https://github.com/spree/spree/releases/tag/v6.0.0.beta1
+  documentation_uri: https://docs.spreecommerce.org/
+  source_code_uri: https://github.com/spree/spree/tree/v6.0.0.beta1
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: EasyPost delivery rates and shipping labels for Spree eCommerce platform
+test_files: []