# 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.

## <mark style="color:red;">How It Works</mark>

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`.

## <mark style="color:red;">Configuration</mark>

The feature requires two **ApplicationSettings** values to be configured.

### <mark style="color:red;">1. TARGET\_PACKING\_DATE\_ATTRIBUTE\_KEY</mark>

* **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"`

### <mark style="color:red;">2. TARGET\_PACKING\_DATE\_FORMAT</mark>

* **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

### <mark style="color:red;">Configuration Examples</mark>

```python
# 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'
)
```

## <mark style="color:red;">Usage Scenarios</mark>

### <mark style="color:red;">Scenario 1: E-commerce Delivery Date</mark>

```python
# 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
```

### <mark style="color:red;">Scenario 2: B2B Scheduled Shipment</mark>

```python
# 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
```

### <mark style="color:red;">Scenario 3: Special Event Date</mark>

```python
# 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
```

## <mark style="color:red;">Error Handling</mark>

### <mark style="color:red;">Invalid Date Format</mark>

```python
# 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
```

### <mark style="color:red;">Missing Configuration</mark>

```python
# ApplicationSettings
TARGET_PACKING_DATE_ATTRIBUTE_KEY = None  # Not set

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

### <mark style="color:red;">Attribute Key Not Found</mark>

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

# ApplicationSettings
TARGET_PACKING_DATE_ATTRIBUTE_KEY = "delivery_date"  # Key not present

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

## <mark style="color:red;">Multiple OrderItem Scenario</mark>

When a package contains multiple OrderItems:

* The **first valid date found** is used.
* Remaining OrderItems are ignored for target packing date determination.

```python
# 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)
```

## <mark style="color:red;">Performance Notes</mark>

* **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.

## <mark style="color:red;">Common Issues & Solutions</mark>

#### Problem: Date format mismatch

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

```python
# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/technical-guides/oms/target-packing-date-feature.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.