# Addon Order Item Configuration

This document describes the technical integration details, configuration requirements, validation rules, and runtime behaviors required to successfully implement and operate the Addon Order feature.

## <mark style="color:red;">1. Objective</mark>

The **Addon Order** feature enables the creation of a **new supplementary order** that is explicitly linked to an **existing main order**.

Key characteristics:

* The addon order:
  * Is created as a **separate order**
  * Is linked to the original order
  * Continues with the **same segment information**

***

## <mark style="color:red;">2. Activation</mark>

The addon order flow is controlled by a **`env` setting of the Commerce service in ACC**.

**Required `env` Setting:**

```
ADDON_BASKET_ENABLED = True
```

<figure><img src="https://2911598027-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlQinVPnOffBiOp126ldR%2Fuploads%2F8lLg5ZpTnvyKqzNRio3q%2Fimage.png?alt=media&#x26;token=b1a46948-bddc-4393-b27f-6b3383888d6c" alt=""><figcaption></figcaption></figure>

**Behavior:**

* When set to `True`:
  * Addon basket creation is allowed
  * `/orders/create-addon-order/` endpoint becomes functional
* When set to `False`:
  * Addon basket creation is blocked
  * Requests fail with a validation error (`order_addon_100_5`)
  * HTTP status code: **406 Not Acceptable**

***

## <mark style="color:red;">3. Basket Namespace Configuration</mark>

Addon orders operate under a **dedicated basket namespace**.

Therefore, default basket validation rules must be updated accordingly.

### <mark style="color:$primary;">3.1.  BASKET\_NAMESPACE\_VALIDATORS</mark>

All namespace-related validations are managed through the `BASKET_NAMESPACE_VALIDATORS` dynamic setting.&#x20;

This configuration allows you to manage the validations applied within the multi-basket feature.

**Key:** `BASKET_NAMESPACE_VALIDATORS`\
**Type:** list\
**Default:**

```json
[ 
   {
       "validator_klass": "omnishop.baskets.validator.NullNamespaceValidator",
       "kwargs": {}
   },
   {
       "validator_klass": "omnishop.baskets.validator.ActiveBasketCountValidator",
       "kwargs": {
           "limit": 5
       }
   }
]
```

To support addon basket namespaces, the following adjustments must be made:

#### <mark style="color:red;">Removing the Null Namespace Validator</mark>

To enable addon basket namespaces, remove the following validator from `BASKET_NAMESPACE_VALIDATORS`:

```json
{
       "validator_klass": "omnishop.baskets.validator.NullNamespaceValidator",
       "kwargs": {}
}
```

#### <mark style="color:red;">Preventing Invalid or Conflicting Namespaces</mark>

To avoid namespace collisions or invalid namespace creation, the following validator **can be added**:

```json
{
       "validator_klass": "omnishop.baskets.validator.ForbiddenAddonNamespaceValidator",
       "kwargs": {}
}
```

#### <mark style="color:red;">Enforcing Addon-Only Basket Creation (Optional)</mark>

If the business requires that **only addon baskets** can be created, the following validator can be enabled:

```json
{
       "validator_klass": "omnishop.baskets.validator.OnlyAddonBasketValidator",
       "kwargs": {}
}
```

Behavior when enabled:

* Basket creation under non-addon namespaces is blocked

{% hint style="danger" %} <mark style="color:red;">**Validator Incompatibility Warning**</mark>

**Addon Basket is not compatible with**:

```
NamespaceDataSourceValidator
```

{% endhint %}

***

## <mark style="color:red;">4. Addon Order Creation API</mark>

#### Endpoint

```
POST /orders/create-addon-order/
```

#### Example Request

```bash
curl --location '{{domain}}/orders/create-addon-order/' \
--data '{
    "order_number": "20956811XXX52916980"
}'
```

#### Runtime Behavior

* If an **active addon basket already exists** for the order:
  * The system returns the existing basket
* If no active addon basket exists:
  * A new addon basket is created
* The addon basket is:
  * Marked as the **main (active) basket**
  * Assigned a namespace in the format:

    ```
    BASKET:ADDON:{order_number}
    ```

If the addon basket is no longer required, the active basket can be changed via standard basket namespace endpoints.

#### Response Scenarios

**Existing Addon Basket**

```json
{
  "message": "Addon order basket already exists.",
  "basket_namespace": "BASKET:ADDON:2095681152916980",
  "basket_id": 395
}
```

**New Addon Basket Created**

```json
{
  "message": "Addon order basket created successfully.",
  "basket_namespace": "BASKET:ADDON:2095681152916980",
  "basket_id": 396
}
```

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

Addon order creation is subject to the following validations.

#### User Authentication Validation

**Error Code:** `order_addon_100_1`

* Only authenticated (logged-in) users can create addon orders
* Guest users are explicitly blocked

#### Order Ownership Validation

**Error Code:** `order_addon_100_2`

* The requesting user must be the **owner of the order**
* Users cannot create addon orders for orders they do not own

#### Order Type Validation

**Error Code:** `order_addon_100_7`

* Only orders with regular type are eligible
* Other order types are rejected

#### Order Status Validation

**Error Code:** `order_addon_100_3`

Addon orders are allowed **only if the main order status is one of**:

* `waiting`
* `payment_waiting`
* `confirmation_waiting`
* `approved`

All other statuses are invalid for addon order creation.

#### Feature Toggle Validation

**Error Code:** `order_addon_100_5`

* Triggered when `ADDON_BASKET_ENABLED` is not `True`
* Response:
  * HTTP Status: **406**
  * Addon basket creation is blocked

**Example Error Response:**

```json
{
    "non_field_errors": "We could not find the order with number 2095681XX152916981. Please check your order number and try again.",
    "error_code": "order_addon_100_2"
}
```

***

## <mark style="color:red;">5. Addon Basket Expiration Handling</mark>

While operating on an addon basket, the **main order status is continuously validated**.

#### Expiration Conditions

* If the main order transitions into a status that no longer allows addon orders:
  * The addon basket is marked as **expired**

#### System Response

* HTTP Status: **410 Gone**
* Basket items are returned for reference
* User is instructed to create a new order

```json
{
    "items": [
        {
            "pk": "8",
            "name": "Phaeton 160x220+60x80+160x240cm Single Satin Duvet Cover Set",
            "quantity": "2"
        }
    ],
    "message": "You can no longer add products to this order. Your basket has expired because the order status has changed. Please create a new order.",
    "code": "order_addon_100_6"
}
```

***

## <mark style="color:red;">6. Checkout Flow Adjustments</mark>

Addon orders reuse the **standard checkout flow** with mandatory exclusions.

#### Skipped Steps

1. The following checkout pages **must be skipped**:
   1. Address Selection Page
   2. Shipping Option Selection Page
2. Standard post-order pages are reused
3. Shipping amount is automatically set to 0 by the system

## <mark style="color:red;">7. Dynamic Settings and Rule Bypass</mark>

During the addon order process, some dynamic configurations are not triggered again.

* The `IDENTITY_NUMBER_REQUIRED_AMOUNT` configuration is not re-evaluated for addon orders.
* Shipping option rules are not re-applied during the addon order stage.

Therefore, these configurations and rules are applied **only to the initial (main) order** and remain valid for the addon order without being recalculated.

***

## <mark style="color:red;">8. Frontend Identification of Addon Basket</mark>

To enable frontend distinction, the basket response includes a `status` field.

#### Example Response

```json
{
    "basket": {
        "basketitem_set": [...],
        "namespace": "BASKET:ADDON:2095681152916980",
        "status": "addon"
    }
}
```

Therefore, frontend can:

* Detect addon basket
* Adjust UI and flow accordingly
* Prevent invalid actions

***

## <mark style="color:red;">9. Newly Created Addon Order Properties</mark>

When checkout is completed:

* A new order is created with:
  * `order_type = addon`
  * `related_order` referencing the main order