# Update Order and Order Item

The Order Update API provides endpoints that allow users to modify specific aspects of an order or its individual items.

## <mark style="color:red;">`PATCH`</mark> <mark style="color:red;">Update Order</mark>

This endpoint allows users to update the `is_send` status of an order. The `is_send` parameter should be set to `true` to indicate that the order has been communicated to the ERP system.

This endpoint does not support updates to other order details. Any modifications beyond `is_send` must be performed through the `/order_items/` endpoint.

The path variable (pk) specifies the order to be updated. If no errors occur, the response will always reflect the order's most recent status.

**Path:** `{omnitron_url}/api/v1/orders/{pk}/`

**Authorization:** `Token <OMNITRON_ACCESS_TOKEN>`

**Request Parameters**

<table><thead><tr><th width="167.625">Parameter</th><th width="165.265625">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>is_send</td><td>boolean</td><td>It should be set to true if ERP is informed about the order.</td></tr></tbody></table>

**Example Request**

```py
import requests
import json

url = "{omnitron_url}/api/v1/orders/{pk}/"

headers = {
    'Authorization': 'Token <OMNITRON_ACCESS_TOKEN>',
    'Content-Type': 'application/json'
}

payload = {
    "is_send": true,
    }
}

response = requests.patch(url, headers=headers, data=json.dumps(payload))
print(response.json)
```

**Example Response (200 OK)**

```json
{
    "pk": 12345,
    "number": "2792097964712363",
    "channel": 1,
    "status": "450",
    "date_placed": "2024-12-17T10:36:59.077305Z",
    "customer": 458899,
    "shipping_address": 122333,
    "billing_address": 122333,
    "currency": "aed",
    "amount": "286.10",
    "shipping_amount": "6.10",
    "shipping_tax_rate": null,
    "extra_field": {
        "custom_note": "Please deliver between 9 AM and 5 PM."
    },
    "payment_option": 332,
    "payment_option_slug": "Credit_Card",
    "bin_number": "555555",
    "installment": 233,
    "installment_count": 1,
    "delivery_type": "standard",
    "installment_interest_amount": "0.00",
    "cargo_company": 34,
    "invoice_number": "INV123456",
    "invoice_date": "2025-01-18T10:00:00Z",
    "e_archive_url": "https://example.com/invoice",
    "refund_amount": "100.00",
    "discount_refund_amount": "0.00",
    "shipping_refund_amount": "0.00",
    "discount_amount": "0.00",
    "is_send": true,
    "net_shipping_amount": "6.10",
    "shipping_interest_amount": "0.00",
    "tracking_number": "TRACK123456",
    "carrier_shipping_code": "CARRIER123",
    "remote_addr": "176.41.48.148",
    "fundstransfertransaction_set": [],
    "has_gift_box": true,
    "gift_box_note": "Happy Birthday!",
    "external_status": 1,
    "client_type": "ios",
    "language_code": "en-us",
    "notes": "Customer requested faster delivery",
    "delivery_range": {
        "lower": "2025-01-20T09:00:00Z",
        "upper": "2025-01-20T18:00:00Z"
    },
    "shipping_option_slug": "cdek-cargo",
    "segment": "VIP",
    "modified_date": "2025-01-18T10:10:00Z",
    "checkout_provider_id": null,
    "created_date": "2024-12-17T10:37:04.440088Z",
    "cancellation_info": {},
    "shipping_company": "cdek",
    "cancel_status": null,
    "defined_tracking_url": "https://example.com/shipment",
    "installment_free": false
}
```

**Example Responses (400 Bad Request)**

```
{"detail": "JSON parse error - Expecting ',' delimiter: line 50 column 5 (char 287)"}
```

```
{"status": ["No matching type."]}
```

## <mark style="color:red;">`PATCH`</mark> <mark style="color:red;">Update Order Item</mark>

This endpoint enables users to update the details of an order item. Request body parameters can be used individually or in combination with others. The path variable (pk) specifies the order item to be updated.

**Path:** `{omnitron_url}/api/v1/order_items/{pk}/`

**Authorization:** `Token <OMNITRON_ACCESS_TOKEN>`

**Request Parameters**

<table><thead><tr><th width="178.0390625">Parameter</th><th width="164.76171875">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>string (enum)</td><td>The status of the order item. Allowed values are order status codes.</td></tr><tr><td>extra_field</td><td>object</td><td>Any JSON data is allowed to be stored with the order item. Endpoint does not update or delete fields which are not included in the JSON data.</td></tr><tr><td>attributes</td><td>object</td><td>An object where all values must be string or boolean. The data in the body will be the final one on the item as a whole.</td></tr><tr><td>attributes_kwargs</td><td>object</td><td>An object where all values must be an object. The nested objects should include additional information about the attributes of the order item. The data in the body will be the final one on the item as a whole.</td></tr><tr><td>cancel_status</td><td>string (enum &#x26; nullable)</td><td>The status of cancellation processes of the order item. Allowed values are included in the cancel status list.</td></tr><tr><td>tracking_number</td><td>string (nullable)</td><td>The tracking number provided by the shipping company for the order item.</td></tr><tr><td>defined_tracking_url</td><td>string (nullable)</td><td>URL for shipment tracking.</td></tr><tr><td>invoice_number</td><td>string (nullable)</td><td>Number value of the invoice related to the order item.</td></tr><tr><td>invoice_date</td><td>string (nullable)</td><td>Date value of the invoice related to the order item and must be formatted as UTC ISO 8601.</td></tr><tr><td>e_archive_url</td><td>string (nullable)</td><td>The URL where the PDF version of the invoice can be accessed. This link allows customers or stakeholders to view and download the invoice directly from the Omnitron panel or integrated sales channels.</td></tr><tr><td>carrier_shipping_code</td><td>string (nullable)</td><td>Tracking code assigned by the carrier.</td></tr><tr><td>shipping_company</td><td>string (enum &#x26; nullable)</td><td>The name of the shipping company assigned to the order item. This field represents the official carrier used for tracking and processing the shipment, such as a general shipping service provider. Allowed values are limited to the companies and their hard-coded defined names in Omnitron.</td></tr><tr><td>parent</td><td>integer or string (nullable)</td><td>The input must be the primary key value of an existing order item.</td></tr><tr><td>shipped_date</td><td>string (nullable)</td><td>The date when the order item was shipped. It must be formatted as UTC ISO 8601.</td></tr><tr><td>delivered_date</td><td>string (nullable)</td><td>The date when the order item was delivered. It must be formatted as UTC ISO 8601.</td></tr><tr><td>estimated_delivery_date</td><td>string (nullable)</td><td>The estimated delivery date for the order item. It must be formatted as YYYY-MM-DD.</td></tr><tr><td>defined_shipping_company</td><td>string (nullable)</td><td>A value representing the actual shipping company that the end user should see, which may differ from the "shipping_company" field. For example, if the internal system uses one shipping service for processing but the actual delivery is handled by a different carrier, this field will contain the name of the carrier responsible for the delivery.</td></tr><tr><td>data_source</td><td>integer or string (nullable)</td><td>The input must be the primary key value of an existing data source. The DataSource model contains detailed information about the seller, supplier, or related data entity.</td></tr><tr><td>shipping_option_group</td><td>integer or string (nullable)</td><td>The input must be the primary key value of an existing shipping option group. Shipping option group value represents the selected shipping option for the order item. For more details see: <a href="https://docs.akinon.com/technical-guides/commerce/data-source-shipping-options">Data Source Shipping Options</a> and <a href="https://docs.akinon.com/technical-guides/commerce/attribute-based-shipping-options">Attribute Based Shipping Options</a>.</td></tr></tbody></table>

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

* Requests to change the status to "cancelled" or "refunded" will be rejected, and no updates will be made to the order item.
* The request body must not include the following attribute fields:
  * `split_from_order_item_pk`
  * `old_order_item_omnitron_id`
  * `old_order_item_id`
  * `old_product_sku`
  * `old_price`
  * `new_product_sku`
  * `new_price`
* If the current `cancel_status` is "approved" for the order item, the request body must include the corresponding field with a non-null value, and its value cannot be "confirmed".
* If the current `cancel_status` is "waiting\_for\_payment" for the order item, the request body must include the corresponding field with a non-null value, and its value cannot be any of the following:
  * `waiting`
  * `confirmation_waiting`
  * `confirmed`, `approved`
  * `rejected`
* If the current status is **100** or **600**, the following fields cannot be updated:
  * `tracking_number`
  * `defined_tracking_url`
  * `defined_shipping_company`.
* If the `status` code in the payload is **500** and the `shipped_date` of the related order item is null, the date will be set to the request time.
* If the `status` code in the payload is **550** and the `delivered_date` of the related order item is null, the date will be set to the request time.
* Including either `invoice_number` or `tracking_number` in the request body will change the order item’s status to 450 if the current status is 400, regardless of the value in the status field of the request body.
* If the request body includes any of the following fields, the order associated with the order item will be updated with the provided values. However, if the order's payment type is "pay on delivery" and the order already has a tracking number, it will remain unchanged:
  * `invoice_number`
  * `invoice_date`
  * `e_archive_url`
  * `tracking_number`
  * `shipping_company`
  * `status`
  * `defined_tracking_url`

**Example Request**

```py
import requests
import json

url = "{omnitron_url}/api/v1/order_items/{pk}/"
headers = {
    'Authorization': 'Token <OMNITRON_ACCESS_TOKEN>',
    'Content-Type': 'application/json'
}
payload = {
    "status": "450",
    "extra_field": {
        "processing_notes": "Special handling required",
        "customer_preference": "Fragile package"
    },
    "attributes": {
        "gift_wrap": true,
        "priority_shipping": true
    },
    "attributes_kwargs": {
        "gift_wrap": {
            "message": "Happy Birthday",
            "paper_color": "gold"
        },
        "priority_shipping": {
            "reason": "Time-sensitive delivery",
            "expedited": true
        }
    },
    "tracking_number": "TRACK789012",
    "defined_tracking_url": "https://tracking.fastexpress.com/TRACK789012",
    "defined_shipping_company": "FastExpress",
    "invoice_number": "INV789012",
    "invoice_date": "2025-01-24T14:30:00Z",
    "e_archive_url": "https://example.com/invoices/789012",
    "carrier_shipping_code": "FAST-789012",
    "shipping_company": "FastExpress",
    "shipped_date": "2025-01-24T15:00:00Z",
    "delivered_date": "2025-01-26T10:00:00Z",
    "estimated_delivery_date": "2025-01-26",
    "cancel_status": null,
    "parent": null,
    "data_source": null,
    "shipping_option_group": null
}

response = requests.patch(url, headers=headers, data=json.dumps(payload))
print(response.text)

```

**Example Response (200 OK)**

```json
{
    "pk": 1340653,
    "order": 946856,
    "product": 1891,
    "status": "450", 
    "price_currency": "try",
    "price": "109.99",
    "tax_rate": "0.18",
    "extra_field": {
        "processing_notes": "Special handling required",
        "customer_preference": "Fragile package",
        "price_extra_field": {},
        "stock_extra_field": {}
    },
    "price_list": 34,
    "stock_list": 34,
    "invoice_number": "INV789012",
    "invoice_date": "2025-01-24T14:30:00Z",
    "e_archive_url": "https://example.com/invoices/789012",
    "tracking_number": "TRACK789012",
    "carrier_shipping_code": "FAST-789012",
    "shipping_company": "FastExpress",
    "shipment_code": null,
    "external_status": null,
    "discount_amount": "11.55",
    "retail_price": "111.99",
    "attributes": {
        "gift_wrap": true,
        "priority_shipping": true
    },
    "attributes_kwargs": {
        "gift_wrap": {
            "message": "Happy Birthday",
            "paper_color": "gold"
        },
        "priority_shipping": {
            "reason": "Time-sensitive delivery",
            "expedited": true
        }
    },
    "image": null,
    "parent": null,
    "shipped_date": "2025-01-24T15:00:00Z",
    "delivered_date": "2025-01-26T10:00:00Z",
    "estimated_delivery_date": "2025-01-26",
    "modified_date": "2025-01-24T08:45:18.831693Z",
    "created_date": "2024-10-11T13:56:35.894193Z",
    "defined_tracking_url": "https://tracking.fastexpress.com/TRACK789012",
    "defined_shipping_company": "FastExpress",
    "cancel_status": null,
    "installment_interest_amount": "0.00",
    "is_tradable": false,
    "datasource": null,
    "localized_attributes": {},
    "localized_attributes_kwargs": {},
    "cancellation_reconciliation": null,
    "reconciliation": null,
    "forced_refund": false,
    "original_stock": 0,
    "shipping_option_group": null
}

```

**Example Responses (400 Bad Request)**

```
{"detail": "JSON parse error - Expecting ',' delimiter: line 50 column 5 (char 287)"}
```

```
{"status": ["No matching type."]}
```

## <mark style="color:red;">`PATCH`</mark> <mark style="color:red;">Update Order Statuses in Bulk</mark>

When the order is invoiced or the shipping process is managed outside of Omnitron, the following endpoint is used to save this order information to Omnitron. Based on this information, Omnitron decides on the cancellation/return processes of the order.

For example, if the delivery processes are controlled from outside of Omnitron (e.g., an ERP system), the status of the order line should be updated when the cargo information is received. The order should be updated with the status information corresponding to the Omnitron order status table along with the tracking number received from the courier company.

**Path:** `{omnitron_url}/api/i1/order_items/bulk_status_update/`

**Authorization:** `Token <OMNITRON_ACCESS_TOKEN>`

**Request Parameters**

<table><thead><tr><th width="171.1484375">Parameter</th><th width="138.0390625">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>id</td><td>Unique identifier for the order item.</td></tr><tr><td>invoice_number</td><td>string</td><td>The invoice number generated for the order item.</td></tr><tr><td>invoice_date</td><td>string</td><td>The date when the invoice was issued. The format is expected to follow ISO 8601 standards, e.g., <code>YYYY-MM-DDTHH:MM:SSZ</code></td></tr><tr><td>e_archive_url</td><td>string</td><td>The URL where the PDF version of the invoice can be accessed. This link allows customers or stakeholders to view and download the invoice directly from the Omnitron panel or integrated sales channels.</td></tr><tr><td>status</td><td>string</td><td>The current status of the order item, mapped to Omnitron's predefined status codes. Allowed values are order status codes.</td></tr><tr><td>tracking_number</td><td>string</td><td>The tracking number provided by the shipping company for the order item.</td></tr><tr><td>shipping_company</td><td>enum</td><td>The name of the shipping company assigned to the order. This field represents the official carrier used for tracking and processing the shipment, such as a general shipping service provider. Allowed values are limited to the companies and their hard-coded defined names in Omnitron.</td></tr></tbody></table>

**Example Request**

```javascript
import requests
import json

url = "{omnitron_url}/api/i1/order_items/bulk_status_update/"

headers = {
    'Authorization': 'Token <OMNITRON_ACCESS_TOKEN>',
    'Content-Type': 'application/json'
}

data = {
    "orderitem_set": [
        {
            # Invoice issued, not shipped
            "id": 1,
            "status": "450",         
            "invoice_number": "SEP123123",
            "invoice_date": "2021-07-14T00:00:00.000000Z",
            "e_archive_url": "http://e.archive.url/SEP123123",
        },
        {
            # Invoice issued and shipped
            "id": 2,
            "status": "500",
            "invoice_number": "SEP123123",
            "invoice_date": "2021-07-14T00:00:00.000000Z",
            "tracking_number": "TR123123",
            "e_archive_url": "http://e.archive.url/SEP123123",
            "shipping_company": "ups"
        },
        {
            # Shipped only
            "id": 3,
            "status": "500",
            "tracking_number": "TR444444",
            "shipping_company": "ups"
        }
    ]
}

response = requests.patch(url, headers=headers , data=json.dumps(data))
print(response.text)
```

**Example Response (200 OK)**

```javascript
[
  {
    "id": 1,
    "order": 1,
    "product_sku": "1185185001",
    "status": "500",
    "price_currency": "try",
    "price": "100.00",
    "tax_rate": "18.00",
    "extra_field": {},
    "price_list": 1,
    "stock_list": 1,
    "cancel_status": null,
    "invoice_number": "SEP123123",
    "invoice_date": "2021-07-14T00:00:00Z",
    "e_archive_url": "http://e.archive.url/SEP123123",
    "installment_interest_amount": "0.00",
    "tracking_number": "11111111",
    "carrier_shipping_code": null,
    "shipping_company": "other",
    "shipment_code": null,
    "external_status": null,
    "discount_amount": "0.00",
    "retail_price": null,
    "attributes": {},
    "attributes_kwargs": {},
    "image": null
  },
  {
    "id": 2,
    "order": 1,
    "product_sku": "1185185002",
    "status": "500",
    "price_currency": "try",
    "price": "86.00",
    "tax_rate": "18.00",
    "extra_field": {},
    "price_list": 1,
    "stock_list": 1,
    "cancel_status": null,
    "invoice_number": "SEP123123",
    "invoice_date": "2021-07-14T00:00:00Z",
    "e_archive_url": "http://e.archive.url/SEP123123",
    "installment_interest_amount": "0.00",
    "tracking_number": "TR123123",
    "carrier_shipping_code": null,
    "shipping_company": "ups",
    "shipment_code": null,
    "external_status": null,
    "discount_amount": "0.00",
    "retail_price": null,
    "attributes": {},
    "attributes_kwargs": {},
    "image": null
  },
  {
    "id": 3,
    "order": 1,
    "product_sku": "1185185003",
    "status": "500",
    "price_currency": "try",
    "price": "17.00",
    "tax_rate": "18.00",
    "extra_field": {},
    "price_list": 1,
    "stock_list": 1,
    "cancel_status": null,
    "invoice_number": "SEP123123",
    "invoice_date": "2021-07-14T00:00:00Z",
    "e_archive_url": "http://e.archive.url/SEP123123",
    "installment_interest_amount": "0.00",
    "tracking_number": "TR444444",
    "carrier_shipping_code": null,
    "shipping_company": "ups",
    "shipment_code": null,
    "external_status": null,
    "discount_amount": "0.00",
    "retail_price": null,
    "attributes": {},
    "attributes_kwargs": {},
    "image": null
  }
]
```

**Example Responses (400 Bad Request)**

If any error occurs during the bulk operation, the response specifies which order\_item is incorrect along with the error messages.

For example:

```javascript
[
    {
        "message": {
            "status": [
                "No matching type."
            ]
        },
        "args": {
            "orderitem_id": "123"
        }
    },
    {
        "message": [
            "You can only update one order at a time."
        ],
        "args": {
            "orderitem_id": "122"
        }
    }
]
```


---

# 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://apidocs.akinon.com/omnitron/integration/order/update-order-and-order-item.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.