spree-shipstation 5.0.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30a88f9939731dc679980577dc0b23a91fdbda25c4019063b3f4728dfb2fe5a9
-  data.tar.gz: d410ae3a207dd0051ab938c3890c60c515b403723ac43392ede48ab872352ca1
+  metadata.gz: 1ec0ccf29f471fcbd60126248195ed5adbb10f9ae5cc5301b23b640308ce6f0f
+  data.tar.gz: 97d83306702cbbac6b67f7d4e2bca35676063e397e7e13717ad4eaed7e0d3487
 SHA512:
-  metadata.gz: f1d456fbe2b2e4a682b7cc2b62e1c07faad779b449bd8f2da72e5a2ce67b9f133b8cb23a214bb62dfd2ba4d1429a6b1b6fc8839597feb3e445a31fd419de5869
-  data.tar.gz: ce40b12b11650ef36d848a709a4a0bd513c654a9ca6da8659728e178dd82cdba573504dbaf7ce981ef67509b986d0a11f47157f21280894dec8c90f2fae56769
+  metadata.gz: 80e0b2aa61bcc31c1a59249d02522b548899cdea0fa5a7dfb04ba03aa24916105c54434495095f598a54a5d8aa472f58be1cfd2a9eb8c48636efcc8f759eaa84
+  data.tar.gz: c3650585bc19e8dd5d89571771b413fa64de828a9f82afd72a899cbb0f751d576367dc8de94bd5d2f18b8e267da6ea84b37cd32a069aa1b12bed3999f530a26f

data/.gitignore

@@ -19,5 +19,4 @@ spec/dummy
 public/spree
 .ruby-version
 .ruby-gemset
-gemfiles/*.gemfile.lock
 *.gem

data/CHANGELOG.md

@@ -2,6 +2,132 @@
 
 All notable changes to this project are documented in this file.
 
+## 6.0.0
+
+Spree 6 support. The major version tracks Spree's, so `spree-shipstation` 6.x
+supports Spree 6, and Spree 5 stays on the 5.0.x releases (the `5-0-stable`
+branch).
+
+**Nothing ShipStation or the merchant has configured has to change** for the
+default store. The `/shipstation` URL, the credentials, the XML, the `ready`
+status and the `OrderNumber` of every fulfillment ShipStation already holds stay
+as they were. A store other than the default moves to its integration's URL
+(below).
+
+**Run `bin/rake spree:upgrade` right after `db:migrate`, before ShipStation next
+polls.** Spree's upgrade tasks move 5.x shipment statuses to fulfillment statuses
+(`ready` and `pending` become `unfulfilled`, `shipped` becomes `fulfilled`),
+backfill the delivery-method providers the pickup rule reads, recompute the
+statuses of orders whose shipments were pending, ready or shipped, encrypt stored
+secrets, and carry `auto_capture_on_dispatch` over to the store's
+`capture_method`. Until then the export is empty. See "Upgrading
+from 5.0" in the README.
+
+**Requirements:** Spree `~> 6.0`, Ruby 3.3 or newer, pagy 43.6 or newer. The 5.x
+releases do not install on Spree 6.
+
+### Changed
+
+- **Orders are exported per fulfillment**, since Spree 6 replaced shipments with
+  fulfillments. `OrderID` is the fulfillment's id and `OrderNumber` its number:
+  the number a fulfillment already had before Spree 6, or `R1001-F1` style
+  (order number, `-F`, position) for new ones. Totals stay order-level, as before.
+- **Only fulfillments Spree will let ship are exported**: placed, still
+  unfulfilled, paid, with nothing backordered, and not a pickup. "Paid" means
+  paid, overcharged or partially refunded; or nothing owed; or, on a store whose
+  capture method is `on_dispatch` or `manual`, authorized, or partially paid with
+  the rest authorized (mixed tender, such as store credit plus a card). As before,
+  unpaid or backordered fulfillments do not appear in ShipStation until they can
+  ship: 5.x exported only `ready` shipments. Results are ordered by last update,
+  oldest first.
+- **Ship notices fulfil through Spree 6's fulfil workflow.** When Spree refuses
+  (an unpaid order, backordered items, a canceled fulfillment) the notice is
+  answered with `400` and Spree's reason, and nothing is recorded. It is never
+  answered `200` for a fulfillment Spree did not ship.
+- **Ship notices are retry-safe.** A notice for a fulfillment that is already
+  fulfilled or delivered only records or corrects the tracking number: it does
+  not fulfil the parcel or publish the event again. A retry that names a tracking
+  number already on another delivery of the same fulfillment is refused with
+  `400` ("Tracking number has already been taken"). Concurrent retries are
+  serialized under the order's row lock. A parcel still marked `shipped` from 5.x,
+  before Spree's upgrade task renames the status, is treated the same way.
+- **A notice without an order number is refused** with `400`. New fulfillments
+  store no number, so a blank one would otherwise match any of them.
+- **Capture on dispatch follows Spree 6's `capture_method`**, set on the store or
+  overridden per payment method. A declined capture answers `400` ("Could not
+  capture payment: ...") and keeps nothing: the fulfillment stays unfulfilled,
+  the payment stays pending and the tracking written during the attempt is rolled
+  back, so the retry starts from the same place.
+- **Shipped notifications are the host app's to send.** Spree 6 core sends no
+  shipped email itself. The fulfil workflow publishes `fulfillment.fulfilled` with
+  `notify_customer` set, and your application's subscriber decides whether, and
+  how, to tell the customer. On a declined capture core publishes that event
+  inside the transaction that is then rolled back, so a subscriber that notifies
+  at once can announce a shipment that did not happen (Spree's own fulfil endpoint
+  behaves the same).
+- `ImageUrl` uses the media's still image, so a video thumbnail exports its
+  poster. It is still a root-relative path.
+- The export returns **50 fulfillments per page**, as documented. (pagy 43, which
+  Spree 6 requires, ignores the option the gem used to set this and would have
+  given 25.) A `page` that is not a number is read as page 1.
+- The integration appears in Spree 6's dashboard under the shipping group, with a
+  description, logo and link to the README. Its form is generated from the
+  username and password preferences. Spree 6's migration copies the password into
+  `secret_preferences` as plain text, and `bin/rake spree:upgrade` encrypts it
+  when Active Record encryption keys are configured.
+- Both endpoints now run on a plain `ActionController::Base` controller, since
+  Spree 6 removed the base controller and helper the 5.x one used.
+
+### Added
+
+- **`/shipstation/<integration id>`** (`GET` and `POST`, with or without `.xml`)
+  serves the store of the active ShipStation integration with that `int_` prefixed
+  id. Spree 6 no longer picks the store from the request's host, so a multi-store
+  host points each store's ShipStation at its own integration's URL. The bare
+  `/shipstation` path is unchanged and belongs to the default store.
+- **Ship notices are matched on ShipStation's `OrderID`** when the notice's XML
+  body carries it. A new fulfillment's number is its place in its order, so when
+  Spree deletes a parcel whose items were all moved out, the parcels after it
+  take new numbers; the `OrderID` (the fulfillment's id) does not change. A notice
+  whose `OrderID` belongs to another order is refused with `400` ("Shipment ...
+  does not match order id ..."), and one for a parcel Spree has deleted since
+  ShipStation imported it is refused with `400` instead of fulfilling the sibling
+  that now has its number; re-import the order from ShipStation. A notice without
+  an `OrderID` is matched on its number.
+- **The `carrier` ShipStation sends** is recorded on the delivery when it matches
+  one of Spree's `tracking_carriers` (for example `UPS` or `Royal Mail`). Otherwise
+  Spree detects the carrier from the tracking number.
+- `GET /shipstation` without the `.xml` extension answers with XML.
+- An integration whose stored username or password is blank refuses every request.
+
+### Removed
+
+- The gem's own payment-capture code and its use of **`auto_capture_on_dispatch`**.
+  Spree 6's `capture_method` replaces that setting, and Spree's upgrade task
+  carries it over to the store's `capture_method`.
+- The `Spree::Shipment` decorator and its `exportable` and `between` scopes. The
+  gem no longer patches core models; `Spree::Shipstation::ExportQuery` selects what
+  is exported.
+- The ERB admin form, the asset manifest and the `spree_extension` dependency.
+
+### Internal
+
+- Specs run against the real routes and Spree's real fulfil workflow, with only
+  ShipStation's side simulated. The suite runs with no deprecation warnings.
+- CI tests the oldest and newest Spree 6 the gem allows (6.0.0 and the latest
+  release) on Ruby 3.3 and 4.0, weekly as well as on pushes.
+
+## 5.0.1
+
+### Fixed
+
+- Export the correct `<Quantity>` for lines ordered more than once. Spree 5 stores
+  a quantity on each `Spree::InventoryUnit` rather than creating one unit row per
+  item, so counting rows reported every line as a quantity of 1 and ShipStation
+  under-picked multi-quantity orders. The quantity is now summed across the
+  line's inventory units, which also keeps a line split across shipments
+  reporting only the units in its own shipment.
+
 ## 5.0.0
 
 First public release on RubyGems, as `spree-shipstation`.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+m.kennedy@me.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Gemfile

@@ -1,14 +1,20 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
-gem "appraisal"
 gem "benchmark"
 gem "brakeman", require: false
 gem "bundler-audit", require: false
-gem "propshaft"
-gem "rails-controller-testing"
 gem "rspec-xsd"
-gem "spree_dev_tools"
+# Constrained here because the gemspec no longer declares it; Bundler 2 would
+# otherwise resolve 0.6.3, which is broken on Spree 6.
+gem "spree_dev_tools", "~> 1.0"
 gem "standard"
 gem "sqlite3"
 
+# CI runs a matrix of Spree versions. SPREE_VERSION pins one (e.g. "6.0.0");
+# left unset, Bundler resolves the newest release the gemspec allows.
+spree_version = ENV.fetch("SPREE_VERSION", "")
+gem "spree", spree_version unless spree_version.empty?
+
 gemspec

data/README.md

@@ -3,15 +3,25 @@
 ![CI](https://github.com/aypex-io/spree-shipstation/workflows/CI/badge.svg)
 ![Standard Rb](https://github.com/aypex-io/spree-shipstation/workflows/Standard%20Rb/badge.svg)
 
-The spree-shipstation integration connects your Spree stores with [ShipStation](https://www.shipstation.com), allowing ShipStation to pull shipments from your store, and when a shipment is sent, update the order with a tracking number and mark it as shipped.
+The spree-shipstation integration connects your Spree stores with [ShipStation](https://www.shipstation.com), allowing ShipStation to pull the fulfillments that are ready to ship from your store, and when one is sent, update the order with a tracking number and mark it as fulfilled.
 
+## Requirements
+
+- Spree 6 (`~> 6.0`)
+- Ruby 3.3 or newer
+
+Spree 5 stores stay on the 5.0.x releases, which live on the [`5-0-stable`](https://github.com/aypex-io/spree-shipstation/tree/5-0-stable) branch:
+
+```ruby
+gem "spree-shipstation", "~> 5.0"
+```
 
 ## Installation
 
 1. Add this extension to your Gemfile with this line:
 
     ```ruby
-    gem "spree-shipstation"
+    gem "spree-shipstation", "~> 6.0"
     ```
 
 2. Install the gem using Bundler
@@ -24,7 +34,7 @@ The extension registers itself with Spree's integration framework automatically
 
 ### Step 1: Configuring Spree
 
-Visit the **Integrations** section of your Spree store and configure the ShipStation integration by creating a unique username and password.
+Visit the **Integrations** section of your Spree dashboard and configure the ShipStation integration (listed with the shipping integrations) by creating a unique username and password. The username is 10 to 30 characters of letters, numbers and `. _ @ + -`; the password is 20 to 60 characters and needs an uppercase letter, a number and a special character, one of `! @ # $ % ^ & * ( ) , . ? " : { } | < >`. Other characters such as `-`, `_`, `+` and `=` may appear but do not count as the special character.
 
 ### Step 2: Configuring ShipStation
 
@@ -34,41 +44,117 @@ Enter the following details:
 
 - **Username**: The username you created in Step 1.
 - **Password**: The password you created in Step 1.
-- **URL to custom page**: `https://your-store-domain.com/shipstation.xml`.
+- **URL to custom page**: `https://shop.example.com/shipstation.xml`.
 
-There are five shipment states for an order (= shipment) in ShipStation. These states do not
-necessarily align with Spree, but you can configure ShipStation to create a mapping for your
-specific needs. Here's the default mapping:
+That URL belongs to your **default store**. Any other store (a multi-store setup) must use the URL that names its ShipStation integration:
 
-ShipStation description | ShipStation status | Spree status
-------------------------|--------------------|---------------
-Awaiting Payment        | `unpaid`           | `pending`
+```
+https://shop.example.com/shipstation/int_abc123.xml
+```
+
+`int_abc123` stands for the integration's prefixed ID, which starts with `int_`. In a Rails console, `Spree::Integrations::Shipstation.all.map(&:prefixed_id)` lists them. The credentials are always the ones set on that integration. The `.xml` is optional on both URLs.
+
+### Order status
+
+Every order the gem sends has the status `ready`, so in ShipStation's Custom Store settings map `ready` to **Awaiting Shipment**. ShipStation's other statuses are never sent: the gem exports only fulfillments that can ship now, and ShipStation marks one as shipped itself once the label exists.
+
+ShipStation description | ShipStation status | Sent by the gem
+------------------------|--------------------|----------------
 Awaiting Shipment       | `paid`             | `ready`
-Shipped                 | `shipped`          | `shipped`
-Cancelled               | `cancelled`        | `cancelled`
-On-Hold                 | `on-hold`          | `pending`
+Anything else           | —                  | never; only `ready` is exported
+
+## What ShipStation pulls
+
+Spree 6 splits an order into fulfillments (parcels), and the gem exports one ShipStation order per fulfillment. An order with several fulfillments therefore appears once for each, every copy carrying the order's totals.
+
+A fulfillment is exported when all of these hold:
+
+- it belongs to the store and is still **unfulfilled**;
+- its order is **placed**, so drafts and canceled orders are left out;
+- its order is **paid**: paid, overcharged or partially refunded; or it owes nothing (a total of zero); or, on a store whose capture method is `on_dispatch` or `manual`, it is only authorized, or partially paid with the rest authorized (mixed tender, such as store credit plus a card) (see [Payment capture](#payment-capture));
+- **none of its items is backordered**;
+- it is **not a pickup**: fulfillments collected in person (pickup or pickup point delivery methods) are not shipped.
+
+Apart from the pickup rule, these are most of the checks Spree makes again when the parcel is fulfilled, so ShipStation is rarely offered a parcel Spree would refuse. When it is fulfilled, Spree also checks that the stock location has the units on hand, and the limits under [Payment capture](#payment-capture) apply. A parcel refused then gets a `400` with Spree's reason.
+
+ShipStation's `start_date` and `end_date` (`MM/DD/YYYY HH:MM`, UTC) limit the export to fulfillments whose own or whose order's last update falls in that window. A date the gem cannot read is ignored. Results are ordered by last update, oldest first.
+
+`OrderID` is the fulfillment's id and `OrderNumber` its number. Fulfillments created on Spree 6 are numbered after their order, for example `R1001-F1`; fulfillments created before 6.0 keep the number they already had, so what ShipStation already holds does not change.
+
+## What happens on a ship notice
+
+When a label is created, ShipStation posts to the same URL with `order_number` (the `OrderNumber` it was given), `tracking_number` and `carrier` in the query string, and the notice again as an XML body that carries the `OrderID` it was given. The gem finds that fulfillment in the store, by its `OrderID` when the body carries one and by its number otherwise, and:
+
+- **fulfils it** through Spree's own fulfil workflow, recording the tracking number, and answers `200`;
+- records the carrier when ShipStation's carrier name matches one of Spree's `tracking_carriers` (for example `UPS`, `USPS`, `FedEx` or `Royal Mail`); otherwise Spree detects it from the tracking number;
+- if the fulfillment is **already fulfilled or delivered**, only records or corrects the tracking number and answers `200`. ShipStation retries, and a retry does not fulfil the parcel or publish the event again. The one exception is a tracking number that is already on a different delivery of the same fulfillment, which is refused (below);
+- otherwise answers `400` with a plain-text reason and changes nothing. ShipStation shows the reason to the warehouse. The reasons include:
+  - `Could not find shipment with number …`, for an unknown or blank number, or an `OrderID` whose fulfillment no longer exists;
+  - `Shipment … does not match order id …`, when the `OrderID` belongs to a fulfillment of another order;
+  - `Tracking number is required`;
+  - `Shipment … is canceled`;
+  - Spree's own message when it refuses to fulfil, for example `This order is not paid for yet`, or its message about backordered units;
+  - `Could not capture payment: …`, when the gateway declines a capture on dispatch;
+  - `Tracking number has already been taken`, when a retry for a fulfilled parcel names a tracking number that already belongs to another delivery of the same fulfillment.
+
+The gem never forces a fulfilment past Spree's paid and backordered checks, and never splits a fulfillment.
+
+### Why the `OrderID` comes first
+
+A new fulfillment's number is its place in its order: `R1001-F2` is the second parcel. When every item is moved out of a parcel (with the dashboard's split or change-location actions, say), Spree deletes it, and the parcels after it move up a place and take new numbers. A fulfillment's id never changes, so the gem trusts the `OrderID` over the number. A notice for a renumbered parcel still fulfils the right one, and a notice for a parcel Spree deleted after ShipStation imported it is refused with a `400` rather than fulfilling a sibling that now has its number. Re-import the order from ShipStation to pick up its parcels as they now are.
+
+So, in an order with several parcels, avoid moving every item out of a parcel ShipStation has already imported: that parcel is no longer valid in ShipStation.
 
 ## Configuration
 
-### Payment capture on dispatch
+### Payment capture
+
+The gem has no capture setting of its own. Capture on dispatch follows Spree 6's `capture_method`, set on the store and optionally overridden by each payment method:
+
+- `checkout` (the default) charges as the order is placed. Authorized orders are not yet paid, so they are not exported.
+- `on_dispatch` authorizes at checkout and charges when the fulfillment is fulfilled. The gem exports authorized orders, and partially paid ones whose rest is authorized, and Spree captures the payment as the ship notice is applied. If the gateway declines, ShipStation gets a `400` ("Could not capture payment: …") and nothing is kept: the fulfillment stays unfulfilled, the payment stays pending and any tracking number written during the attempt is rolled back. The next retry, or the merchant's fix to the payment, fulfils it.
+- `manual` authorizes at checkout and leaves charging to your staff. The gem exports authorized and partially paid orders, and Spree lets them ship without charging them.
+
+Two limits:
 
-The integration respects Spree's `auto_capture_on_dispatch` setting. When enabled in your Spree store, pending payments are captured automatically before a shipment is marked as shipped. If a payment capture fails, an error is returned to ShipStation (HTTP 400), preventing the shipment from being marked as shipped until the issue is resolved.
+- Whether an authorized or partially paid order is exported depends on the **store's** capture method only. A store that captures at checkout but has a payment method that overrides it to `on_dispatch` never exports that method's authorized orders, and does so silently. To export them, set the store's capture method to `on_dispatch` or `manual`, bearing in mind that this changes it for every payment method that has no setting of its own. In the reverse case, a store set to `on_dispatch` with a payment method overridden to capture at checkout, an authorized order is exported and the ship notice is then refused with Spree's reason.
+- A partially refunded order is exported, because the rest of it may still ship, but Spree compares the net captured amount (after refunds) with what the order was due, so the ship notice may still be refused with Spree's reason. Likewise a partially paid order ships only while the rest is authorized on payment methods that defer capture.
 
-Payment capture happens **synchronously** within the shipnotify webhook request (inside a database transaction) so that a shipment is never marked as shipped against an uncaptured payment. ShipStation automatically retries failed webhook deliveries, and the operation is designed to be safe to repeat: a shipment that is already `shipped` is not shipped again, and only still-pending payments are captured. If your payment gateway is slow, be aware that the capture round-trip occurs in the request cycle.
+### Fulfillment providers
+
+Give the delivery methods whose parcels ShipStation ships Spree's **Manual** fulfillment provider. On a ship notice, Spree's fulfil workflow also buys a label and tells the delivery method's provider that the parcel has shipped; for Manual, both do nothing. A provider that buys labels or hands parcels to a 3PL would act a second time for a parcel ShipStation has already shipped. A declined capture on dispatch does not undo those calls either, even though everything Spree wrote is rolled back.
+
+### Telling the customer
+
+Spree core does not send a shipped email by itself (as of Spree 6.0.1). When a fulfillment is fulfilled, Spree publishes the `fulfillment.fulfilled` event, and the gem asks for the customer to be notified (`notify_customer: true`). Your application decides whether, and how, to tell the customer, by subscribing to `fulfillment.fulfilled`. Without a subscriber, no shipped email goes out.
+
+One caveat: when a capture on dispatch is declined, Spree publishes `fulfillment.fulfilled` synchronously inside the transaction that is then rolled back. A subscriber that notifies at once, rather than after the transaction commits, can tell a customer their order has shipped when the attempt was declined and nothing was kept. Spree's own fulfil endpoint behaves the same way, so if that matters to you, make your subscriber send only after the transaction has committed.
 
 ### Pagination
 
-The export endpoint returns up to **50 shipments per page**. ShipStation handles pagination automatically using the `page` query parameter.
+The export endpoint returns up to **50 fulfillments per page**. ShipStation handles pagination automatically using the `page` query parameter; a `page` that is not a number is read as the first page.
+
+## Upgrading from 5.0
+
+- Bump the gem to `~> 6.0` alongside your upgrade to Spree 6.
+- The gem has no data migration of its own. Spree 6's migrations rename shipments to fulfillments, keeping their ids and numbers, and copy the integration's password into `secret_preferences` as plain text. `bin/rake spree:upgrade` (next step) encrypts it when Active Record encryption keys are configured.
+- **Run `bin/rake spree:upgrade` right after `db:migrate`, before ShipStation next polls.** Spree's upgrade tasks move 5.x shipment statuses to fulfillment statuses (`ready` and `pending` become `unfulfilled`, `shipped` becomes `fulfilled`), backfill the delivery-method providers the pickup rule reads, recompute the payment and fulfillment statuses of orders whose shipments were pending, ready or shipped, encrypt stored secrets, and carry settings such as `auto_capture_on_dispatch` over to the store's `capture_method`. An order in another state, such as partly shipped or backordered, keeps its 5.x payment status until Spree next updates it. Until then the export is empty, since no fulfillment is `unfulfilled` yet. Meanwhile a parcel still marked `shipped` is treated as fulfilled: a ship notice only records its tracking.
+- **ShipStation needs no changes** for the default store: same URL, same credentials, same `OrderNumber` for parcels it has already imported, same `ready` status.
+- New fulfillments are numbered like `R1001-F1`. A store other than the default must use `/shipstation/<integration id>` (see Step 2): 5.x picked the store from the request's host, and Spree 6 does not, so the bare URL serves only the default store.
+- Capture on dispatch now follows Spree 6's `capture_method` setting (on the store or the payment method). Spree's upgrade task carries `auto_capture_on_dispatch` over to the store's `capture_method`.
+- As before, unpaid or backordered fulfillments do not appear in ShipStation until they can ship: 5.x exported only `ready` shipments.
+- A ship notice for something Spree will not ship is answered with `400` and Spree's reason.
+- Spree 6 core sends no shipped email on its own, so subscribe to `fulfillment.fulfilled` if your store relied on the 5.x email (see [Telling the customer](#telling-the-customer)).
 
 ## Security considerations
 
-- **Serve the endpoints over HTTPS.** Both `/shipstation` endpoints authenticate with HTTP Basic Auth, which transmits the configured username and password (base64-encoded) on every request. Always terminate these requests over TLS in production so the credentials are not exposed in transit. Credentials are compared in constant time to avoid timing attacks.
-- **Consider rate limiting.** The gem does not throttle authentication attempts. If you want brute-force protection, add it at the application or edge layer (for example, [`rack-attack`](https://github.com/rack/rack-attack)). The enforced credential length (10–30 character username, 20–60 character complex password) already makes guessing impractical.
-- **Response codes.** When no active ShipStation integration is configured, the endpoints respond with `404` before authentication is checked; a configured-but-unauthenticated request responds with `401`. This is intentional, but be aware it reveals whether the integration is configured.
+- **Serve the endpoints over HTTPS.** Both `/shipstation` endpoints authenticate with HTTP Basic Auth, which transmits the configured username and password (base64-encoded) on every request. Always terminate these requests over TLS in production so the credentials are not exposed in transit. Credentials are compared in constant time to avoid timing attacks, and an integration whose stored username or password is blank refuses every request.
+- **Consider rate limiting.** The gem does not throttle authentication attempts. If you want brute-force protection, add it at the application or edge layer (for example, [`rack-attack`](https://github.com/rack/rack-attack) or Rails' `rate_limit`). The enforced credential length (10–30 character username, 20–60 character complex password) already makes guessing impractical.
+- **Response codes.** When no active ShipStation integration is configured, the endpoints respond with `404` before authentication is checked; a configured-but-unauthenticated request responds with `401`. This is intentional, but be aware it reveals whether the integration is configured. An integration that is switched off is the same as none.
 
 ## Performance
 
-The export query eager-loads its association graph to avoid N+1 queries. The `exportable` scope filters shipments by `state` and orders them by `updated_at`, joining and filtering orders by their `updated_at`. The gem ships no migrations of its own; on large stores, ensure the relevant Spree core columns (`spree_shipments.state`, `spree_shipments.updated_at`, `spree_orders.updated_at`) are adequately indexed in your application's database.
+The export query eager-loads its association graph to avoid N+1 queries. It selects unfulfilled fulfillments, joins their orders and filters by payment status, and orders and windows by `updated_at`. The gem ships no migrations of its own. Spree 6's schema indexes `spree_fulfillments.status` and `spree_orders.payment_status`, but not `spree_fulfillments.updated_at` or `spree_orders.updated_at`; on large stores, consider indexing those two in your application's database.
 
 ## Usage
 
@@ -76,9 +162,10 @@ There's nothing you need to do. Once properly configured, the integration just w
 
 ### Compatibility
 
-This extension works with the following Spree versions:
-- 5.x
-
+spree-shipstation | Spree | Ruby
+------------------|-------|------
+6.0.x             | 6.x (`~> 6.0`) | 3.3 or newer
+5.0.x, on [`5-0-stable`](https://github.com/aypex-io/spree-shipstation/tree/5-0-stable) | 5.x | 3.1 or newer
 
 ### Testing
 
@@ -94,6 +181,13 @@ To run the tests use:
 bundle exec rake
 ```
 
+CI runs the suite against Spree 6.0.0 and the newest 6.x release. To test against a specific Spree version locally:
+
+```shell
+SPREE_VERSION=6.0.0 bundle update spree
+bundle exec rake
+```
+
 ### Code Formatting
 
 To check your code formatting with [Standard Rb](https://github.com/testdouble/standard) run:
@@ -110,11 +204,14 @@ bundle exec standardrb --fix
 
 ## Releasing
 
-```bash
-bundle exec gem bump -p -t
-bundle exec gem release
-```
+Bump `Spree::Shipstation::VERSION` in `lib/spree/shipstation/version.rb`, add the release to the changelog, and merge. Pushing a `v*` tag publishes the gem to RubyGems through the Release workflow.
 
 ## License
 
 Copyright (c) 2021-2026 Matthew Kennedy, released under the MIT License.
+
+## Code of Conduct
+
+Everyone interacting in this project's codebases, issue trackers, and
+communication channels is expected to follow the [code of
+conduct](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler"
 Bundler::GemHelper.install_tasks
 
@@ -21,19 +23,18 @@ task :test_app do
   # literal `require ENV['LIB_NAME']` and templates the same string into the
   # generated spec/dummy/config/application.rb.
   ENV["LIB_NAME"] = "spree/shipstation"
-  Rake::Task["extension:test_app"].execute(
-    install_admin: true
-  )
+  # Spree 6's extension:test_app takes no install_admin option.
+  Rake::Task["extension:test_app"].execute
 end
 
 namespace :dummy do
   # Spree's test_app task runs `db:migrate` in the generator's own process with
-  # output redirected to /dev/null and its exit status ignored. On the heavier
-  # Spree 5.3+/5.4 setup path (admin install + Tailwind/asset build) that step
-  # can be interrupted mid schema-dump, leaving a TRUNCATED db/schema.rb. Rails
-  # then loads that broken dump on the next migrate and fails, so the dummy
-  # database ends up empty and the whole suite errors with
-  # "Could not find table 'spree_*'".
+  # output redirected to /dev/null and its exit status ignored. If a migration
+  # fails partway (for example, Spree's preferences conversion eager loads the
+  # whole app, so any class that fails to load stops it), the dummy database is
+  # left half-built and the whole suite errors with weird failures or
+  # "Could not find table 'spree_*'", with no hint of the cause. Rails then
+  # loads a possibly truncated db/schema.rb dump on the next migrate too.
   #
   # Make setup deterministic: discard any (possibly corrupt) schema dump and
   # rebuild the database from the migration files, in a fresh process and