Order Replacement and Weight Change Actions

This document describes all order-level actions related to product replacement, weight changes, capture, and additional payment handling.

Each action includes endpoint definitions, request/response structures, validation rules, business constraints, audit behavior, and configuration dependencies.

1. Capture Order

This action is executed only once per order.

It captures the order’s previously authorized transaction. This operation converts the prior authorization obtained from the customer into an actual payment.

Endpoint

POST /api/v1/orders/{order_id}/capture_order/

Request Example

POST /api/v1/orders/12345/capture_order/
Authorization: Token your_token_here
Content-Type: application/json

{
  "force_refund": false
}

Request Parameters

force_refund (boolean, optional, default: false)
- If the order already has a purchase transaction, setting this value to true triggers a refund for the excess amount and applies a capture-like behavior.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

(Empty response body)

Business Rules

This action must be executed only once per order.
If the order has an authorized transaction, the order status cannot be waiting_for_substitute.
- Otherwise, FinalizeCaptureWaitingPaymentException is raised.
Concurrent capture attempts are blocked.
- A cache lock prevents multiple captures on the same order for 60 seconds.
The order total amount is validated via:
```
order.validate_total_amount()
```
The order must have either:
- an authorize transaction, or
- a purchase transaction
- Otherwise, OrderCaptureException is raised.
If force_refund = true and the order already has a purchase transaction:
- The excess amount of the purchase transaction is refunded.
If the order status is confirmation_waiting, it is updated to approved.
An audit log entry is created with action:
```
order_capture
```

ENV & Dynamic Settings

ENV: None
Dynamic Settings: None

2. Bulk Replace Products

It bulk replaces the products of multiple order items in an order.

The existing order items are canceled, and new order items are created with the new products.

Endpoint

POST /api/v1/orders/{order_id}/bulk_replace_products/

Request Example

POST /api/v1/orders/12345/bulk_replace_products/
Authorization: Token your_token_here
Content-Type: application/json

[
  {
    "order_item": 100,
    "new_product_sku": "NEW_PRODUCT_SKU_123"
  },
  {
    "order_item": 101,
    "new_product_sku": "NEW_PRODUCT_SKU_456"
  }
]

Request Parameters

order_item (integer, optional): ID of the order item to be replaced.
new_product_sku (string, optional): SKU of the replacement product.

Validation Note

At least one of order_item or new_product_sku must be provided.
If both are missing, serializer validation fails.

Response Example

{
  "pk": 12345,
  "number": "ORD-2024-001",
  "status": "approved",
  "amount": "1500.00",
  "currency": "TRY",
  "orderitem_set": [
    {
      "pk": 200,
      "price": "1500.00",
      "status": "approved"
    }
  ]
}

Business Rules

Each request item must include at least one of the order_item or new_product_sku parameters. If neither is provided, a serializer validation error is raised.
The order status must be one of the following:
- confirmation_waiting
- approved
- preparing Otherwise, OrderItemChangeOrderNotAllowedException is raised.
The order’s channel type must be web. Otherwise, OrderItemChangeOrderNotAllowedException is raised.
The order transaction is validated (validate_transaction()).
The order must not have been sent to the ERP system (is_send=False). Otherwise, OrderItemReplacementOrderIsSendException is raised.
For each order item:
- The order item must not have an active cancellation plan.
- The order item status must be one of: waiting, payment_waiting, confirmation_waiting, approved, preparing.
- The new product must belong to the same catalog.
- The new product must be in the same stock list.
- The stock quantity of the new product must not be less than the order item’s quantity.
- The stock unit type must be quantity.
- The price of the new product must be greater than the order item’s total benefit share amount.
If the new order amount is greater than the previous amount:
- The ORDER_ITEM_UPPER_PRICE_ENABLE dynamic setting must be enabled. Otherwise, OrderItemPriceExceedsCurrentPriceException is raised.
- The order status is updated to waiting_for_substitute.
- A create_replacement_order event is sent to Commerce.
The existing order items are canceled (status=cancelled, price=0).
New order items are created.
The order amount is recalculated.
An audit log entry is created with the action:
```
order_change_product
```

ENV & Dynamic Settings

ENV: None
Dynamic Settings
- ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE (boolean, default: false): Determines whether order item product updates are enabled.
- ORDER_ITEM_UPPER_PRICE_ENABLE (boolean, default: false): Allows the new product price to be higher than the existing price.

3. Bulk Reduce Weights

It bulk reduces the weights of multiple order items in an order. This operation is used for products sold by kilogram.

This action does not allow weight increase.

Endpoint

POST /api/v1/orders/{order_id}/bulk_reduce_weights/

Request Example

POST /api/v1/orders/12345/bulk_reduce_weights/
Authorization: Token your_token_here
Content-Type: application/json

[
  {
    "order_item": 100,
    "new_weight": 2.5
  },
  {
    "order_item": 101,
    "new_weight": 1.8
  }
]

Request Parameters

order_item (integer, required): The ID of the order item whose weight will be changed.
new_weight (decimal, required): The new weight value (in kilograms).

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pk": 12345,
  "number": "ORD-2024-001",
  "status": "approved",
  "amount": "1200.00",
  "currency": "TRY",
  "orderitem_set": [
    {
      "pk": 100,
      "price": "1200.00",
      "attributes": {
        "unit_weight": "2.5",
        "old_unit_weight": "3.0"
      },
      ...
    }
  ],
  ...
}

Business Rules

The ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE dynamic setting must be enabled OR the ORDER_ITEM_WEIGHT_KEY setting must be defined. Otherwise, OrderItemReplacementNotEnabledException is raised.
The order transaction is validated by calling validate_transaction().
For each order item:
- The order item must not have an active cancellation plan.
- The order item status must be one of the following: waiting, payment_waiting, confirmation_waiting, approved, preparing.
- The stock unit type must be kilogram.
- The ORDER_ITEM_WEIGHT_KEY key must exist in the order item’s attributes field.
- The new weight must be different from the previous weight.
The price is recalculated based on the weight change ratio:
- new_price = old_price * (new_weight / old_weight)
- If new_weight = 0, the order item price is set to 0, and all benefit applicants are cancelled.
The order item’s attributes field is updated as follows:
- old_{ORDER_ITEM_WEIGHT_KEY}: stores the previous weight
- {ORDER_ITEM_WEIGHT_KEY}: stores the new weight
If the new order total amount is greater than the previous total:
- The ORDER_ITEM_UPPER_PRICE_ENABLE dynamic setting must be enabled. Otherwise, OrderItemPriceExceedsCurrentPriceException is raised.
- The order status is updated to waiting_for_substitute.
- A create_replacement_order event is sent to Commerce.
The order total amount is recalculated.
An audit log entry is created with the action:
```
bulk_order_item_change_weight
```

ENV & Dynamic Settings

ENV
- ORDER_ITEM_WEIGHT_KEY (string, default: None): The key name used to store weight information in the order item’s attributes field (e.g. "unit_weight").
Dynamic Settings
- ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE (boolean, default: False): Determines whether order item updates are enabled.
- ORDER_ITEM_UPPER_PRICE_ENABLE (boolean, default: False): Allows the price calculated from the new weight to be higher than the previous price.

4. Bulk Replace Product and Reduce Weight

Replaces the products of multiple order items in an order and/or reduces their weights. This action allows both product replacement and weight reduction to be performed within the same request.

Endpoint

POST /api/v1/orders/{order_id}/bulk_replace_product_and_reduce_weight/

Request Example

POST /api/v1/orders/12345/bulk_replace_product_and_reduce_weight/
Authorization: Token your_token_here
Content-Type: application/json

[
  {
    "order_item": 100,
    "new_product_sku": "NEW_PRODUCT_SKU_123"
  },
  {
    "order_item": 101,
    "new_weight": 2.5
  }
]

Request Parameters

order_item (integer, optional): The ID of the order item to be updated.
new_product_sku (string, optional): The SKU of the new product (for product replacement).
new_weight (decimal, optional): The new weight value (for weight reduction).

Notes:

new_product_sku and new_weight cannot be provided at the same time. If both are provided, a validation error is raised.
At least one of new_product_sku, new_weight, or order_item must be provided. If none are provided, a validation error is raised.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pk": 12345,
  "number": "ORD-2024-001",
  "status": "approved",
  "amount": "1500.00",
  "currency": "TRY",
  "orderitem_set": [...],
  ...
}

Business Rules

Each request item must include at least one of the following parameters: new_product_sku, new_weight, or order_item. If none are provided, a serializer validation error is raised.
new_product_sku and new_weight cannot be provided together in the same request item. If both are provided, a serializer validation error is raised.
The ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE dynamic setting must be enabled OR the ORDER_ITEM_WEIGHT_KEY setting must be defined. Otherwise, OrderItemReplacementNotEnabledException is raised.
The order transaction is validated by calling validate_transaction().
For each order item:
- If new_product_sku is provided, all business rules of the bulk_replace_products action apply.
- If new_weight is provided, all business rules of the bulk_reduce_weights action apply.
Product replacement and weight reduction can both be applied to the same order item, executed sequentially.
If the new order total amount is greater than the previous total:
- The ORDER_ITEM_UPPER_PRICE_ENABLE dynamic setting must be enabled. Otherwise, OrderItemPriceExceedsCurrentPriceException is raised.
- The order status is updated to waiting_for_substitute.
- A create_replacement_order event is sent to Commerce.
The order total amount is recalculated.
An audit log entry is created with the action:
```
order_bulk_replace_product_and_change_weight
```

ENV and Dynamic Settings

ENV
- ORDER_ITEM_WEIGHT_KEY (string, default: None): The key name used to store weight information in the order item’s attributes field.
Dynamic Settings
- ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE (boolean, default: False): Determines whether order item updates are enabled.
- ORDER_ITEM_UPPER_PRICE_ENABLE (boolean, default: False): Allows the new price to be higher than the previous price.

5. Bulk Change Weight

Updates the weights of multiple order items within an order in bulk (the weight can be increased or decreased).

The difference from the bulk_reduce_weights action is that this action also allows weight increases.

Endpoint

POST /api/v1/orders/{order_id}/bulk_change_weight/

Request Example

POST /api/v1/orders/12345/bulk_change_weight/
Authorization: Token your_token_here
Content-Type: application/json

[
  {
    "order_item": 100,
    "new_weight": 3.5
  },
  {
    "order_item": 101,
    "new_weight": 2.0
  }
]

Request Parameters

order_item (integer, required): The ID of the order item whose weight will be changed.
new_weight (decimal, required): The new weight value (in kilograms).

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pk": 12345,
  "number": "ORD-2024-001",
  "status": "waiting_for_substitute",
  "amount": "1800.00",
  "currency": "TRY",
  "orderitem_set": [
    {
      "pk": 100,
      "price": "1800.00",
      "attributes": {
        "unit_weight": "3.5",
        "old_unit_weight": "2.5"
      },
      ...
    }
  ],
  ...
}

Business Rules

The ORDER_ITEM_UPPER_PRICE_ENABLE dynamic setting must be enabled. Otherwise, OrderItemPriceExceedsCurrentPriceException is raised.
The ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE dynamic setting must be enabled OR the ORDER_ITEM_WEIGHT_KEY setting must be defined. Otherwise, OrderItemReplacementNotEnabledException is raised.
The order transaction is validated by calling validate_transaction().
All business rules of the bulk_reduce_weights action apply.
The weight may be increased or decreased, but it must be different from the previous weight.
If the new order total amount is greater than the previous total:
- The order status is updated to waiting_for_substitute.
- A create_replacement_order event is sent to Commerce.
The order total amount is recalculated.
An audit log entry is created with the action:
```
bulk_order_item_change_weight
```

ENV and Dynamic Settings

ENV
- ORDER_ITEM_WEIGHT_KEY (string, default: None): The key name used to store weight information in the order item’s attributes field.
Dynamic Settings
- ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE (boolean, default: False): Determines whether order item updates are enabled.
- ORDER_ITEM_UPPER_PRICE_ENABLE (boolean, default: False): MANDATORY – must be enabled for this action.

6. Bulk Replace Product and Change Weight

Allows replacing products and/or changing the weight of multiple order items within an order. Unlike the bulk_replace_product_and_reduce_weight action, this endpoint allows both increasing and decreasing the weight.

Endpoint

POST /api/v1/orders/{order_id}/bulk_replace_product_and_change_weight/

Request Example

POST /api/v1/orders/12345/bulk_replace_product_and_change_weight/
Authorization: Token your_token_here
Content-Type: application/json

[
  {
    "order_item": 100,
    "new_product_sku": "NEW_PRODUCT_SKU_123"
  },
  {
    "order_item": 101,
    "new_weight": 3.5
  }
]

Request Parameters

order_item (integer, required): ID of the order item to be updated
new_product_sku (string, optional): SKU of the new product to replace the existing one
new_weight (decimal, optional): New weight value for the order item

Validation Rules

order_item is required for each request item.
At least one of new_product_sku or new_weight must be provided.
new_product_sku and new_weight cannot be provided together in the same request item.
- If both are provided, a serializer validation error is raised.
new_weight must be different from the current weight (both increase and decrease are allowed).

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pk": 12345,
  "number": "ORD-2024-001",
  "status": "waiting_for_substitute",
  "amount": "2000.00",
  "currency": "TRY",
  "orderitem_set": [...],
  ...
}

Business Rules

The ORDER_ITEM_UPPER_PRICE_ENABLE dynamic setting must be enabled.
- Otherwise, OrderItemPriceExceedsCurrentPriceException is raised.
At least one of the following conditions must be met:
- ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE dynamic setting is enabled
- ORDER_ITEM_WEIGHT_KEY ENV setting is defined
- Otherwise, OrderItemReplacementNotEnabledException is raised.
The order transaction is validated (validate_transaction()).
All business rules defined for the bulk_replace_product_and_reduce_weight action also apply.
The order total amount is recalculated.
If the new order amount is greater than the previous amount:
- Order status is updated to waiting_for_substitute.
- A create_replacement_order event is sent to Commerce.
An audit log is created after the operation
- Action name: order_bulk_replace_product_and_change_weight

ENV and Dynamic Settings

ENV
- ORDER_ITEM_WEIGHT_KEY (string, default: None): Key name used to store weight information in the order item’s attributes field
Dynamic Settings
- ORDER_ITEM_PRODUCT_UPDATE_AVAILABLE (boolean, default: False): Determines whether order item updates are enabled
- ORDER_ITEM_UPPER_PRICE_ENABLE (boolean, default: False): MANDATORY – Must be enabled for this action

7. Waive Additional Payment

Cancels a pending additional payment (pay later) request for an order and updates the order status to preparing.

This action is used when an order is waiting for an additional payment from the customer, but the payment request is waived.

Endpoint

POST /api/v1/orders/{order_id}/waive_additional_payment/

Request Example

POST /api/v1/orders/12345/waive_additional_payment/
Authorization: Token your_token_here
Content-Type: application/json

(Empty request body)

Request Parameters

This action does not require a request body.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pk": 12345,
  "number": "ORD-2024-001",
  "status": "preparing",
  "amount": "1500.00",
  "currency": "TRY",
  "channel": {...},
  "customer": {...},
  "orderitem_set": [...],
  ...
}

Business Rules

The order status must be waiting_for_substitute.
- Otherwise, PayLaterInfoInvalidOrderStatusException is raised.
The order must have an active PayLaterInfo record with status=payment_waiting.
- If not found, PayLaterInfoNotFoundFromOrderException is raised.
The order status is updated to preparing.
The related PayLaterInfo record is updated to waived.
The operation is executed within an atomic transaction.

ENV and Dynamic Settings

ENV: None
Dynamic Settings: None

General Notes

Error Handling

All actions may raise the following exceptions under relevant conditions:

OrderItemHasActiveCancellationPlanException
- The order item has an active cancellation plan.
OrderItemReplacementNotAllowedException
- Order item replacement is not allowed.
OrderItemReplacementOrderIsSendException
- The order has already been sent.
OrderItemPriceExceedsCurrentPriceException
- The new price exceeds the current price and ORDER_ITEM_UPPER_PRICE_ENABLE is disabled.
OrderCaptureException
- The order transaction cannot be captured.
PayLaterInfoNotFoundFromOrderException
- No pay later information exists for the order.

Audit Logs

All actions create an audit log entry. These logs are used to track and audit order-related operations.

Channel Integration

Some actions (product replacement, weight change) send events to Commerce:

order_item_create – When a new order item is created
order_item_update – When an order item is updated
order_update – When the order is updated
create_replacement_order – When an additional payment is required

Transaction Validation

All replacement-related actions validate the order transaction:

The order must not be captured
The transaction must be in authorize or purchase state

PreviousCancellation Strategies NextCommerce

Last updated 3 days ago

Was this helpful?

Good morning

1. Capture Order

Endpoint

Request Example

Request Parameters

Response Example

Business Rules

ENV & Dynamic Settings

2. Bulk Replace Products

Endpoint

Request Example

Request Parameters

Response Example

Business Rules

ENV & Dynamic Settings

3. Bulk Reduce Weights

Endpoint

Request Example

Request Parameters

Response Example

Business Rules

ENV & Dynamic Settings

4. Bulk Replace Product and Reduce Weight

Endpoint

Request Example

Request Parameters

Response Example

Business Rules

ENV and Dynamic Settings

5. Bulk Change Weight

Endpoint

Request Example

Request Parameters

Response Example

Business Rules

ENV and Dynamic Settings

6. Bulk Replace Product and Change Weight

Endpoint

Request Example

Request Parameters

Response Example

Business Rules

ENV and Dynamic Settings

7. Waive Additional Payment

Endpoint

Request Example

Request Parameters

Response Example

Business Rules

ENV and Dynamic Settings

General Notes

Error Handling

Audit Logs

Channel Integration

Transaction Validation