Target Packing Date Feature

The Target Packing Date feature allows the target packing date to be dynamically determined during the package creation process. This functionality leverages date values stored in the attributes field of OrderItem objects and can override the default calculation logic.

By enabling this feature, businesses can adapt package creation dates to meet special customer requests, scheduled deliveries, or business-specific requirements instead of relying solely on system-defined defaults.

How It Works

During the package creation process, the system determines the target_packing_date in the following order of priority:

1. Manually provided target_packing_date Passed as a parameter to the create_package method.

2. Dynamic date from OrderItem attributes Extracted based on the configured attribute key and format.

3. Default calculation Computed as order.date_placed + stock_location.get_target_packing_interval.

Configuration

The feature requires two ApplicationSettings values to be configured.

1. TARGET_PACKING_DATE_ATTRIBUTE_KEY

• Description: The attribute key to be searched within OrderItem.attributes.

• Type: String

• Default: None (feature disabled)

• Example values:

  • "delivery_date"

  • "scheduled_date"

  • "target_ship_date"

2. TARGET_PACKING_DATE_FORMAT

• Description: The date format expected for parsing the attribute value (Python strptime format).

• Type: String

• Default: "%d/%m/%Y" (DD/MM/YYYY)

• Example values:

  • "%d/%m/%Y" → 25/12/2024

  • "%Y-%m-%d" → 2024-12-25

  • "%d.%m.%Y" → 25.12.2024

  • "%m/%d/%Y" → 12/25/2024

Configuration Examples

# Example using Django Admin or a settings service
settings_service = get_settings_service()

# Activate the feature by setting the attribute key
settings_service.upsert_setting(
    'TARGET_PACKING_DATE_ATTRIBUTE_KEY', 
    'delivery_date'
)

# Define the expected date format
settings_service.upsert_setting(
    'TARGET_PACKING_DATE_FORMAT', 
    '%d/%m/%Y'
)

Usage Scenarios

Scenario 1: E-commerce Delivery Date

# OrderItem.attributes
{
    "delivery_date": "31/12/2024",
    "customer_notes": "New Year's gift"
}

# ApplicationSettings
TARGET_PACKING_DATE_ATTRIBUTE_KEY = "delivery_date"
TARGET_PACKING_DATE_FORMAT = "%d/%m/%Y"

# Result: Package.target_packing_date = December 31, 2024

Scenario 2: B2B Scheduled Shipment

# OrderItem.attributes
{
    "scheduled_shipment": "2024-01-15",
    "warehouse_code": "WH001",
    "priority": "high"
}

# ApplicationSettings
TARGET_PACKING_DATE_ATTRIBUTE_KEY = "scheduled_shipment"
TARGET_PACKING_DATE_FORMAT = "%Y-%m-%d"

# Result: Package.target_packing_date = January 15, 2024

Scenario 3: Special Event Date

# OrderItem.attributes
{
    "event_date": "15.02.2024",
    "event_type": "wedding",
    "special_packaging": true
}

# ApplicationSettings
TARGET_PACKING_DATE_ATTRIBUTE_KEY = "event_date"
TARGET_PACKING_DATE_FORMAT = "%d.%m.%Y"

# Result: Package.target_packing_date = February 15, 2024

Error Handling

Invalid Date Format

# OrderItem.attributes
{
    "delivery_date": "2024-12-25"  # Incorrect format (YYYY-MM-DD)
}

# ApplicationSettings
TARGET_PACKING_DATE_FORMAT = "%d/%m/%Y"  # Expected: DD/MM/YYYY

# Result:
# - Warning log: "Invalid date format for orderitem 123. Expected format: %d/%m/%Y, got: 2024-12-25"
# - Fallback: Default calculation
# - Package.target_packing_date = order.date_placed + interval

Missing Configuration

# ApplicationSettings
TARGET_PACKING_DATE_ATTRIBUTE_KEY = None  # Not set

# Result:
# - Feature is disabled
# - Default calculation is used

Attribute Key Not Found

# OrderItem.attributes
{
    "customer_notes": "Express delivery"
}

# ApplicationSettings
TARGET_PACKING_DATE_ATTRIBUTE_KEY = "delivery_date"  # Key not present

# Result:
# - Skipped silently
# - Default calculation is used

Multiple OrderItem Scenario

When a package contains multiple OrderItems:

• The first valid date found is used.

• Remaining OrderItems are ignored for target packing date determination.

# OrderItems in the package
orderitems = [
    {
        "id": 1,
        "attributes": {"customer_notes": "Standard"}  # No date
    },
    {
        "id": 2, 
        "attributes": {"delivery_date": "25/12/2024"}  # Valid date
    },
    {
        "id": 3,
        "attributes": {"delivery_date": "30/12/2024"}  # Ignored
    }
]

# Result: 25/12/2024 is used (first valid date found)

Performance Notes

• O(n) complexity: The check is linear relative to the number of OrderItems.

• Early exit: The loop terminates as soon as a valid date is found.

• Lazy evaluation: If TARGET_PACKING_DATE_ATTRIBUTE_KEY is None, no checks are performed.

Common Issues & Solutions

Problem: Date format mismatch

Solution: Ensure the format in ApplicationSettings matches the attribute value.

# Incorrect
TARGET_PACKING_DATE_FORMAT = "%d/%m/%Y"
attribute_value = "2024-12-25"

# Correct
TARGET_PACKING_DATE_FORMAT = "%Y-%m-%d"
attribute_value = "2024-12-25"

---

Problem: Feature not working

Checklist:

1. Is TARGET_PACKING_DATE_ATTRIBUTE_KEY configured?

2. Does the OrderItem.attributes contain the specified key?

3. Is the date format correct?

4. Are there warning logs?

---

Problem: Wrong date is used

Cause: In multi-OrderItem packages, the first valid date is applied.

Solution:

• Ensure all OrderItems share the same date, or

• Implement custom logic for selection if needed.