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.

1. Objective

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

---

2. Activation

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

Required env Setting:

ADDON_BASKET_ENABLED = True

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

---

3. Basket Namespace Configuration

Addon orders operate under a dedicated basket namespace.

Therefore, default basket validation rules must be updated accordingly.

3.1. BASKET_NAMESPACE_VALIDATORS

All namespace-related validations are managed through the BASKET_NAMESPACE_VALIDATORS dynamic setting.

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

Key: BASKET_NAMESPACE_VALIDATORS Type: list Default:

[ 
   {
       "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:

Removing the Null Namespace Validator

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

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

Preventing Invalid or Conflicting Namespaces

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

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

Enforcing Addon-Only Basket Creation (Optional)

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

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

Behavior when enabled:

• Basket creation under non-addon namespaces is blocked

Validator Incompatibility Warning

Addon Basket is not compatible with:

NamespaceDataSourceValidator

---

4. Addon Order Creation API

Endpoint

POST /orders/create-addon-order/

Example Request

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

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

New Addon Basket Created

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

Validation Rules

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:

{
    "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"
}

---

5. Addon Basket Expiration Handling

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

{
    "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"
}

---

6. Checkout Flow Adjustments

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

7. Dynamic Settings and Rule Bypass

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.

---

8. Frontend Identification of Addon Basket

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

Example Response

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

Therefore, frontend can:

• Detect addon basket

• Adjust UI and flow accordingly

• Prevent invalid actions

---

9. Newly Created Addon Order Properties

When checkout is completed:

• A new order is created with:

  • order_type = addon

  • related_order referencing the main order