README

Partial Delivery Plugin

Introduction

The Partial Delivery plugin for Shopware 6 enables merchants to manage and track partial shipments for individual order items. This is especially useful in scenarios where an order cannot be fulfilled all at once and must be shipped in multiple packages.It ensures that customers receive available items as soon as possible without having to wait for the entire order to be ready. This improves customer satisfaction and keeps logistics transparent and organized.

Key Features

Track Partial Shipments
- Enables tracking of multiple packages per order item.
- Each package has its own quantity and tracking number.
Custom Admin Tab for Shipments
- Adds a new “Shipment” tab in the Order Detail view.
- View and manage all partial deliveries directly in the admin panel.
Multiple Entries per Line Item
- Supports recording several shipments for the same item.
- Useful for cases like backorders or separate warehouse fulfillment.

Compatibility

✅ Shopware 6.6.x

Get Started

Prerequisites

Important Requirement
The Partial Delivery plugin requires the Shopware Commercial edition to function properly.
Make sure Shopware Commercial is installed and active before proceeding.

Installation & Activation

Download

Git

Clone the Plugin Repository:
Open your terminal and run the following command in your Shopware 6 custom plugins directory (usually located at custom/plugins/):

git clone https://github.com/solution25com/partial-delivery-shopware-6-solution25.git

Packagist

  composer require solution25/partial-delivery

Install the Plugin in Shopware 6

Log in to your Shopware 6 Administration panel.
Navigate to Extensions > My Extensions.
Locate the newly cloned plugin and click Install.

Activate the Plugin

After installation, click Activate to enable the plugin.
In your Shopware Admin, go to Settings > System > Plugins.
Upload or install the “PartialDelivery” plugin.
Once installed, toggle the plugin to activate it.

Verify Installation

After activation, you will see PartialDelivery in the list of installed plugins.
The plugin name, version, and installation date should appear as shown in the screenshot below.

Plugin Configuration

The Partial Delivery plugin does not require any specific configuration after installation. Once activated, it automatically adds a "Shipment" tab in the Order Detail view in the Shopware Admin panel.

If the tab does not appear immediately after installation, run the following commands in your Shopware terminal:

bin/build-administration.sh

These commands will rebuild the admin interface to ensure the shipment tab is visible.

How It Works

1. Customer Places an Order
When a customer places an order, the full quantity of each product is recorded in the order under the Quantity column.

2. Admin Creates a Shipment
From the order’s Shipments tab, the admin can manually create a shipment by clicking the Create Shipment button.

3. Partial Shipment Entry
Instead of shipping the full quantity, the admin can enter a partial quantity to ship (e.g., only 5 out of 20 units).

Each partial shipment can include:

Quantity
A custom box label (e.g., “package 1”)
Tracking number

4. Shipment Details Are Tracked Each shipment is tracked under Shipment Details, showing:

Box name
Shipped quantity
Tracking info

This allows multiple packages to be associated with a single order.

5. Order Status and Fulfillment Management

The Shipped column updates based on the total quantity sent.
Any remaining quantity stays unshipped, allowing future partial shipments.
Full visibility is maintained of what has been shipped vs. what is pending.

Best Practices

Consistent Labeling: Use consistent naming for box labels (e.g., "Package 1", "Box A") to easily identify shipments.
Track Everything: Always enter tracking numbers for each shipment to maintain full shipment history.
Data Cleanup: Periodically review old shipment records to ensure clarity and accuracy in your order management.
Test Before Use: Try the partial delivery flow in a staging environment to confirm expected behavior before using it on live orders.

Admin API Documentation

This document describes the custom Admin API endpoints provided by the Partial Delivery Plugin for Shopware 6. These endpoints allow authorized users to create and retrieve partial shipment data associated with order line items.

🔧 Create Partial Deliveries

Endpoint

POST /api/_action/partial-shipment-delivery

Description

Creates one or more partial delivery entries for specific orderLineItemIds. Each entry must include:

quantity to ship
package name
trackingCode for the shipment

The system validates:

Quantity does not exceed what’s remaining from the originally ordered quantity
Valid orderLineItemIds
Required fields are present

Request Headers

Authorization: Bearer Content-Type: application/json

Example Request Body

{
  "partialDeliveries": [
    {
      "orderLineItemId": "0195a178f96b7345ad27051c34609e52",
      "quantity": 4,
      "package": "Package 6",
      "trackingCode": "DHL12sad31e279"
    },
    {
      "orderLineItemId": "0195a3aea0447296bc5377d49ab95c1e",
      "quantity": 1,
      "package": "Package 2",
      "trackingCode": "1234ABCD789"
    }
  ]
}

Successful Response

{
  "insertedIds": [
    "0195a178f96b7345ad27051c34609e52",
    "0195a3aea0447296bc5377d49ab95c1e"
  ],
  "skippedItems": []
}

Example Error Response (Skipped Items)

{
  "insertedIds": [],
  "skippedItems": [
    {
      "index": 0,
      "orderLineItemId": "{{invalid-id}}",
      "reason": "Invalid or missing orderLineItemId or the quantity exceeded"
    }
  ]
}

📦 Get Shipments by Order ID

GET /api/_action/shipment/{orderId}

Description Fetches all partial deliveries grouped by line item for a given order. Each result shows:

Line item ID
Ordered quantity
Associated shipment(s) with quantity, package, tracking code, and timestamp

Example Request

GET /api/_action/shipment/5b6a139e54e54ed7b7997c71f6f56f9e

Example Response

[
  {
    "lineItemId": "0195a3aea0447296bc5377d49ab95c1e",
    "quantityOrdered": 3,
    "shipments": [
      {
        "quantity": 1,
        "package": "Package 2",
        "trackingCode": "12334ASDAD9",
        "createdAt": "2025-05-22T14:36:12+00:00"
      }
    ]
  },
  {
    "lineItemId": "0195a178f96b7345ad27051c34609e52",
    "quantityOrdered": 4,
    "shipments": [
      {
        "quantity": 4,
        "package": "Package 6",
        "trackingCode": "DHL12sad31e279",
        "createdAt": "2025-05-22T14:36:12+00:00"
      }
    ]
  }
]

🔐 Authentication All endpoints require a valid Admin API Bearer token. You can obtain this token using the standard Shopware Admin API authentication process.

Troubleshooting

Shipment Tab Not Visible in Admin?
- Make sure the Partial Delivery plugin is installed and activated.
- Confirm that the Shopware Commercial extension is installed and active, as it is a required dependency.
- Rebuild the admin interface using the following command:
```
bin/build-administration.sh
```
Plugin not visible in Extensions?
- Clear the cache and refresh the plugin list:
```
bin/console cache:clear
bin/console plugin:refresh
```
Errors when submitting shipments?
- Double-check that all required fields are filled in:
- Quantity
- Box name
- Tracking number

FAQ

Can I create multiple shipments for the same item?
- Yes. Each shipment entry can have its own quantity and tracking data.
Is there a limit to how many shipments I can add per order?
- No hard limit is enforced by the plugin. You can add as many shipment entries as needed per item or order.
Do I need to install additional plugins to use the shipment features?
- To use the full shipment functionality, ensure that the required dependencies, such as the Shopware Commercial extension, are installed and active.

solution25 / partial-delivery

Maintainers

Details