=== ParcelBridge – FluentCart to ShipStation ===
Tags: shipstation, fluentcart, shipping, tracking, ecommerce
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: fluent-cart
Stable tag: 0.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connects FluentCart to ShipStation: orders go to ShipStation, tracking numbers come back, customers get a tracking link.

== Description ==

FluentCart has no ShipStation integration. This plugin connects the two through ShipStation's standard **Custom Store** connector, so no ShipStation API plan is needed.

* Paid physical orders import into ShipStation with address, items, SKUs, weights, the requested shipping method and package info.
* Unpaid offline orders wait under *Awaiting Payment*; refunds and cancellations drop out of ShipStation.
* When you mark an order shipped or buy a label in ShipStation, the tracking number goes back to FluentCart and the order switches to *Shipped* through FluentCart's own status API, so its activity log and emails run as usual.
* FluentCart's shipped email gets a tracking box with a button to the carrier's tracking page.
* Fully paid orders can be set to *Completed* automatically.
* The settings page includes a request log, an export preview and an order inspector for troubleshooting.

**Beta.** Tested end to end with a ShipStation trial account; not yet tested with real purchased labels. This is a community project, not affiliated with FluentCart or ShipStation.

== External services ==

ParcelBridge exchanges order and shipment data with ShipStation, and its tracking button links to carrier and tracking websites. What is sent where, and when:

= ShipStation =

ShipStation is the shipping platform this plugin connects your store to; it is used to import orders for shipping and to report shipments back.

ShipStation's servers call a REST endpoint on your site (`/wp-json/parcelbridge/v1/shipstation`), authenticated with the username and password shown on the ParcelBridge settings page. The endpoint is only called by ShipStation, whenever it imports orders (on its own schedule or when you refresh your store in ShipStation) and when a shipment is created. On import, your site returns the data needed to ship each paid physical order changed in the requested time window: order number, dates, status and totals; the customer's name, email address, phone number and shipping address; the order note; and the line items (name, SKU, quantity, price, weight, product image URL). When a shipment is created, ShipStation sends the carrier, service and tracking number to your site.

This service is provided by Auctane (ShipStation): [terms of service](https://www.shipstation.com/terms-of-service/), [privacy policy](https://www.shipstationglobal.com/privacy-policy/).

= Carrier and package tracking websites =

The tracking button that ParcelBridge adds to FluentCart's "order shipped" email links to a tracking page, so your customer can follow the parcel. The link contains the tracking number. Nothing is sent to these websites by the plugin; the tracking number only reaches the website when the customer clicks the button, and the customer's browser then talks to that website directly.

Which website the button opens depends on the carrier ShipStation reports:

* DHL / Deutsche Post (dhl.com): [terms of use](https://www.dhl.com/de-de/home/fusszeile/nutzungsbedingungen.html), [privacy notice](https://www.dhl.com/de-en/home/footer/privacy-notice.html)
* UPS (ups.com): [terms of use](https://www.ups.com/us/en/support/shipping-support/legal-terms-conditions/website-terms-of-use), [privacy notice](https://www.ups.com/us/en/support/shipping-support/legal-terms-conditions/privacy-notice)
* FedEx (fedex.com): [terms of use](https://www.fedex.com/en-us/terms-of-use.html), [privacy notice](https://www.fedex.com/en-us/trust-center/privacy.html)
* USPS (usps.com): [terms of use](https://about.usps.com/who/legal/terms-of-use.htm), [privacy policy](https://about.usps.com/who/legal/privacy-policy/full-privacy-policy.htm)
* Royal Mail (royalmail.com): [terms of use](https://www.royalmail.com/terms-website), [privacy notice](https://www.royalmail.com/privacy-notice)
* Canada Post (canadapost-postescanada.ca): [terms of use](https://www.canadapost-postescanada.ca/cpc/en/support/kb/company-policies/terms-conditions/legal-terms-of-use-and-conditions.page), [privacy policy](https://www.canadapost-postescanada.ca/cpc/en/our-company/transparency-and-trust/privacy-centre/privacy-policy.page)
* Australia Post (auspost.com.au): [terms of use](https://auspost.com.au/about-us/about-our-site/website-terms-conditions), [privacy policy](https://auspost.com.au/privacy)

For any other carrier, the button opens a universal tracking website, chosen under Settings → ParcelBridge (you can also choose no link at all):

* 17TRACK (17track.net), the default: [terms of service](https://www.17track.net/en/about/licensing), [privacy policy](https://www.17track.net/en/about/privacy)
* Parcels (parcelsapp.com): [terms of use](https://parcelsapp.com/en/terms), [privacy policy](https://parcelsapp.com/en/privacy)

You can also enter your own tracking links for other carriers in the settings; those websites are then your choice.

== Installation ==

1. Upload the plugin and activate it. FluentCart must be active.
2. Open **Settings → ParcelBridge** and copy the URL, username and password.
3. In ShipStation: Settings → Selling Channels → Store Setup → Connect a Store or Marketplace → **Custom Store**. Paste the three values and enter the status names exactly as shown on the settings page.
4. Click *Test Connection* in ShipStation, then add a Ship From location.

If a security plugin restricts the WordPress REST API for visitors who aren't logged in, allow the route `/wp-json/parcelbridge/v1/shipstation`.

== Frequently Asked Questions ==

= Do I need a paid ShipStation plan? =

The Custom Store connector is part of ShipStation's regular plans; the plugin was developed with the free trial.

= Is the ShipStation password a WordPress account? =

No. ParcelBridge generates its own username and password for this one endpoint. They give access to nothing else on your site.

= Why doesn't ShipStation show the weight? =

The plugin sends item weights as ShipStation's Custom Store format specifies. On a trial account without a connected carrier, ShipStation showed 0 kg anyway. Check with the order inspector that a weight was found, and report your results.

= Where is the tracking box in the email? =

After the greeting's intro text. For an exact spot, put `[parcelbridge_tracking]` into FluentCart's "order shipped" email template.

== Upgrade Notice ==

= 0.3.0 =
New ShipStation URL and new settings key. After updating, copy the URL, username and password from Settings → ParcelBridge into ShipStation's store settings again.

== Changelog ==

= 0.3.0 =
* ShipStation endpoint is now a WordPress REST route with a permission callback and a sanitizing argument schema.
* Shipping and order status are set through FluentCart's status API directly, without switching users.
* XML responses are escaped on output with wp_kses().
* All names use the `parcelbridge` prefix; settings are removed on uninstall.
* External services documented in full.

= 0.2.0 =
* Renamed to ParcelBridge.

= 0.1.9 =
* WordPress Plugin Check fixes; readme.txt added.

See CHANGELOG.md for earlier versions.
