=== JD Web & Ship ===
Contributors: coderkube
Tags: woocommerce, shipping, logistics, order-fulfillment, india-shipping
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.3.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Seamlessly integrate JD Web & Ship logistics with WooCommerce for automated order processing and shipment tracking in India.

== Description ==

A smart dropshipping platform built to simplify e-commerce shipping.

JD Web & Ship is a powerful dropshipping solution built for WooCommerce merchants. It streamlines ecommerce shipping by connecting multiple courier partners instantly, comparing real-time rates, and automating order fulfillment with tracking.

**Key Benefits:**

* Multi-courier integration for flexibility
* Real-time shipping rates comparison
* Automated order syncing & fulfillment
* End-to-end shipment tracking
* COD support & reconciliation reports

= Key Features =

* **Automatic Order Sync** - Processing orders are automatically sent to JD Web & Ship
* **Manual Order Management** - Send individual or bulk orders manually
* **Automatic Order Completion** - WooCommerce order is marked as "Completed" when all JD orders are delivered
* **Real-time Tracking** - Display shipment status and tracking information on order pages
* **Customer Tracking** - Customers can view shipping status in their My Account area
* **India-Focused** - Specifically designed for Indian addresses and postal codes
* **Order Filtering** - Automatically filters and processes only Indian orders
* **Webhook Support** - Receive real-time status updates from JD Web & Ship
* **Detailed Logging** - Track all sync activities and API responses
* **Retry Failed Orders** - Easy retry mechanism for failed shipments
* **Prepaid/COD Support** - Handles both payment methods
* **Product Image Sync** - Sends one product image per order item to JD Web & Ship
* **Improved Localization** - Refined text labels and status messages for better clarity

= Workflow =

1. Customer places an order on your WooCommerce store
2. Order status changes to "Processing"
3. Plugin automatically sends order details to JD Web & Ship
4. JD Web & Ship creates shipment and assigns courier
5. Tracking information is updated in WooCommerce
6. Customer receives tracking details in their account
7. Real-time status updates via webhook
8. If all JD shipments are delivered, the WooCommerce order is automatically marked as "Completed"

= Automatic Order Completion =

* WooCommerce order is automatically marked as **Completed** when:
  - All JD sub-orders reach "Delivered" status
* Order completion is triggered via JD Web & Ship webhook updates
* Partial delivery does NOT complete the order
* Ensures accurate fulfillment tracking

= Product Image Sync =

* One product image is included per order item in the API payload sent to JD Web & Ship
* For variable products, the variation's own image is used if set; otherwise the parent product image is used as fallback
* Ensures JD Web & Ship always receives an accurate visual reference for each shipped item

= Requirements =

* WooCommerce 5.0 or higher
* Active JD Web & Ship account with API credentials
* Valid email and phone number for all orders
* Orders must have Indian shipping addresses

= Supported Order Statuses =

* Processing orders are automatically synced
* Failed orders can be retried manually
* Cancelled orders trigger cancellation at JD Web & Ship

== External Services ==

This plugin connects to JD Web & Ship API for order fulfillment and shipment tracking.

**Service Details:**
* Service Provider: JD Web & Ship (https://jdwebnship.com/)
* API Endpoint: https://api.jdwebnship.com/api/
* Purpose: Automated order processing, shipment creation, and tracking updates

**Data Transmitted:**
When an order is placed on your WooCommerce store, the following data is sent to JD Web & Ship API:
* Customer name, email, and phone number
* Shipping and billing addresses (India only)
* Order items, quantities, SKUs
* Product image URL (one image per item — variation image preferred, parent image as fallback)
* Order totals and payment method (COD/Prepaid)
* Store domain and webhook URL for status updates

**When Data is Sent:**
* Automatically when order status changes to "Processing"
* Manually via admin "Send to JD" button
* When order is cancelled (cancellation request)

**Legal Information:**
* Terms of Service: https://jdwebnship.com/terms
* Privacy Policy: https://jdwebnship.com/privacy

By using this plugin, you consent to transmitting customer order data to JD Web & Ship for shipping processing. Please ensure your store's Privacy Policy discloses this data sharing with customers.

== Installation ==

= Automatic Installation =

1. Log in to your WordPress admin panel
2. Navigate to Plugins > Add New
3. Search for "JD Web & Ship"
4. Click "Install Now" and then "Activate"

= Manual Installation =

1. Download the plugin zip file
2. Log in to your WordPress admin panel
3. Navigate to Plugins > Add New > Upload Plugin
4. Choose the downloaded zip file and click "Install Now"
5. Activate the plugin

= Configuration =

1. Go to **JD Web & Ship > Settings**
2. Enter your JD Web & Ship email and password
3. Click "Save Settings" to authenticate
4. Enable "JD Shipping" to start processing orders
5. Go to **Pages > Checkout > Edit** (for block checkout)
6. Make email and phone fields required in checkout settings

= Important Setup for Block Checkout =

If you're using WooCommerce Block Checkout:

1. Go to **Pages > Checkout > Edit**
2. Select the Checkout block
3. Open **Customer Information** settings
4. Enable **Required** for:
   - Email address
   - Phone number
5. Click **Update**

This ensures all orders have the necessary contact information for shipping.

== Frequently Asked Questions ==

= Do I need a JD Web & Ship account? =

Yes, you need an active JD Web & Ship account with API credentials (email and password).

= Does this plugin work with all countries? =

No, this plugin is specifically designed for Indian addresses. Orders with non-Indian shipping addresses will be automatically skipped.

= How do I get JD Web & Ship API credentials? =

Contact JD Web & Ship https://jdwebnship.com/ support to create an account and obtain your API credentials.

= What happens if an order fails to sync? =

Failed orders are marked in the order list with error details. You can retry individual orders or bulk retry from the Order Sync page.

= Can customers track their shipments? =

Yes, tracking information is displayed in the customer's My Account > Orders section with direct tracking links.

= Does this work with WooCommerce subscriptions? =

The plugin syncs orders when they reach "Processing" status, which works with subscription renewals.

= How do I make email and phone required? =

For **Classic Checkout**: Already handled automatically by the plugin.
For **Block Checkout**: Follow the setup instructions in the Installation section.

= What shipping methods are supported? =

JD Web & Ship supports multiple courier partners. The best courier is automatically assigned based on destination and package details.

= Can I cancel orders after they're sent to JD? =

Yes, when you cancel an order in WooCommerce, the plugin automatically sends a cancellation request to JD Web & Ship.

= Is there a log to track sync activities? =

Yes, go to **JD Web & Ship > Order Sync** to view all sync activities, errors, and API responses.

= Does this plugin modify my checkout page? =

For classic checkout, it makes email and phone required. For block checkout, you need to manually enable these settings.

= What happens during plugin deactivation? =

The plugin will be automatically deactivated if WooCommerce is deactivated. All data remains in the database.

= How do I reset my JD connection? =

Go to **JD Web & Ship > Settings** and click "Reset JD Connection" to clear credentials and reconnect. This automatically sends a logout request to JD to deauthorize and disconnect the store.

= What API URL does the plugin use? =

The plugin communicates with the JD Web & Ship remote API endpoints at `https://zlfarwpweupu.jdwebnship.com/api/`.

= Which product image is sent to JD Web & Ship? =

For simple products, the main product image is sent. For variable products, the variation's own image is used when available; if the variation has no dedicated image, the parent product's main image is used as a fallback. Only one image per item is included in the payload.

== Screenshots ==

1. Settings page - Configure JD Web & Ship API credentials
2. Order Sync page - Manual sync and bulk order management
3. Order admin column - View shipping status in order list
4. Customer My Account - Tracking information display
5. Order details - Shipping information in admin order page
6. Retry failed orders - Easy retry mechanism

== Changelog ==

= 1.3.1 =
* Changed api endpoint.

= 1.3 =
* Added automatic remote logout on JD side when the JD connection is reset.
* Cleaned up and simplified API endpoint routing logic by removing prefix candidates.

= 1.2.3 =
* Updated JD Web & Ship authentication endpoint.

= 1.2.2 =
* Added product image URL to order item payload sent to JD Web & Ship
* Variation image is used when set; falls back to parent product image automatically
* Empty string sent when no product image is available (prevents payload errors)

= 1.2.1 =
* Fixed showing failed jd order status in the old order becuase of webhook update

= 1.2 =
* Added smart handling for edited WooCommerce orders
* Implemented item-level delinking to prevent duplicate shipments
* Improved webhook handling to ignore delinked items
* Enhanced multi-item and single-item order sync behavior
* Added logging for delinked items and improved admin display

= 1.1 =
* Added automatic WooCommerce order completion when all JD orders are delivered
* Enhanced status handling and edge-case coverage
* Improved text labels and localization
* Improved order sync validation and stability
* Prevented duplicate or invalid API calls
* Enhanced logging and webhook handling

= 1.0 =
* Initial release
* Automatic order synchronization
* Manual and bulk order sync
* Real-time webhook support
* Customer tracking display
* Failed order retry mechanism
* India address filtering
* Detailed activity logging

== Upgrade Notice ==

= 1.3 =
Cleans up API routing endpoints and adds automatic remote logout on JD side when connection is reset.

= 1.2.3 =
Updates the JD Web & Ship login/authentication endpoint. Please re-save your API credentials under JD Web & Ship > Settings after updating.

= 1.2.2 =
Adds product image sync to the JD Web & Ship order payload. No configuration required — images are resolved automatically per item.

= 1.0 =
Initial release of JD Web & Ship integration for WooCommerce.

== Additional Information ==

= Support =

For support, please contact:
* Email: support@jdwebnship.com
* Website: https://jdwebnship.com/contact

= Privacy Policy =

This plugin sends order data (customer name, address, phone, email, order items) to JD Web & Ship API for shipment processing. Please ensure your privacy policy reflects this data sharing.

Data transmitted includes:
* Customer contact information
* Shipping and billing addresses
* Order items and quantities
* Product image URLs (one per item)
* Order totals and payment method

= Developer Information =

**Action Hooks:**
* `woocommerce_order_status_processing` - Triggers automatic sync
* `woocommerce_order_status_cancelled` - Triggers order cancellation

**Filter Hooks:**
* `woocommerce_checkout_fields` - Makes email/phone required

**Database Tables:**
* `{prefix}_jdws_sync_logs` - Stores sync activity logs

**Options:**
* `jdws_options` - Plugin settings
* `jdws_webhook_token` - Webhook security token

= Credits =

Developed by CoderKube Technologies Team

== Technical Details ==

= Minimum Requirements =

* WordPress 5.8 or higher
* WooCommerce 5.0 or higher
* PHP 7.4 or higher
* MySQL 5.6 or higher
* HTTPS enabled (recommended)

= API Endpoints Used =

* Login/Authentication
* Order Placement
* Order Cancellation
* Webhook Registration

= Compatibility =

* WooCommerce Classic Checkout 
* WooCommerce Block Checkout 
* HPOS compatibility

= Performance =

* Lightweight and optimized
* Asynchronous processing
* Efficient database queries
* Minimal server load

= Advanced Logic =

* Prevents duplicate or invalid order sync requests
* Item-level filtering to avoid duplicate shipments
* Auto-completion logic based on webhook delivery confirmation
* Loop protection during admin-triggered sync
* Smart product image resolution (variation → parent fallback)

= Order Edit & Item Sync Behavior (New) =

This version introduces advanced handling for WooCommerce orders that are modified after being synced with JD Web & Ship.

= Multi-Item Orders (Multiple Products) =

When an order contains multiple items and the admin updates the order:

* If the admin:
  - Changes order status (e.g., Processing to On Hold)
  - Removes one or more existing items
  - Adds new items

Then:

* Removed items are **delinked** from JD Web & Ship:
  - No cancellation request is sent to JD for removed items
  - They are no longer tracked in active WooCommerce shipment display
  - Future webhook updates from JD for those items are completely ignored and will not update WooCommerce data

* Newly added items:
  - A **new JD shipping order is created**
  - Only new items are sent to JD

* Existing active items:
  - Continue as-is (no duplicate shipment created)

= Important Behavior =

* Delinked items:
  - Will NOT receive further status updates from JD
  - Will NOT affect WooCommerce order completion logic
  - Are kept only for history/reference

* This ensures:
  - No duplicate shipments
  - No accidental cancellations
  - Clean separation between old and new items

= Single-Item Orders =

When an order has only one item:

* If the admin:
  - Removes the item
  - Adds a new item
  - Updates the order

Then:

* The system **reuses the existing JD order**
* No new JD shipment is created
* The existing JD order reference is reused for the updated item

= Delinked Item Behavior =

* Delinked items are NOT displayed in:

  - Admin Order Page
  - Customer My Account -> Orders

Delinked items are internally marked and strictly excluded from:

  - Shipment tracking display (admin and customer)
  - Webhook status updates (incoming JD updates are ignored)
  - Any further synchronization or processing

* Even if JD sends status updates for these items, they will not affect WooCommerce in any way.

= Why This Matters =

This feature prevents:

* Duplicate shipping orders
* Incorrect cancellations
* Conflicts between WooCommerce edits and JD fulfillment
* Webhook updates affecting outdated items

It ensures accurate syncing even when orders are modified after initial processing.

== Troubleshooting ==

= Orders not syncing automatically =

1. Check if "Enable JD Shipping" is turned on
2. Verify your API credentials are correct
3. Ensure orders have Indian shipping addresses
4. Check that email and phone are filled

= "Failed to authenticate" error =

1. Verify your JD Web & Ship email and password
2. Check internet connectivity
3. Contact JD Web & Ship https://jdwebnship.com/ support to verify account status

= Tracking information not showing =

1. Ensure webhook is registered (automatic on first save)
2. Check that JD Web & Ship can reach your website
3. Verify webhook URL is accessible (not behind firewall)

= Phone/Email validation error =

1. For block checkout, manually enable required fields
2. For classic checkout, the plugin handles this automatically

= Product image not appearing in JD dashboard =

1. Ensure the product has a featured image set in WooCommerce
2. For variable products, check if the variation has its own image; if not, the parent image is used automatically
3. Verify your media files are publicly accessible (not behind a login wall)

== License ==

This plugin is licensed under GPLv2 or later.