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.

`PATCH` Update Order

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

Parameter	Data Type	Description
is_send	boolean	It should be set to true if ERP is informed about the order.

Example Request

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)

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

`PATCH` Update Order Item

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

Parameter	Data Type	Description
status	string (enum)	The status of the order item. Allowed values are order status codes.
extra_field	object	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.
attributes	object	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.
attributes_kwargs	object	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.
cancel_status	string (enum & nullable)	The status of cancellation processes of the order item. Allowed values are included in the cancel status list.
tracking_number	string (nullable)	The tracking number provided by the shipping company for the order item.
defined_tracking_url	string (nullable)	URL for shipment tracking.
invoice_number	string (nullable)	Number value of the invoice related to the order item.
invoice_date	string (nullable)	Date value of the invoice related to the order item and must be formatted as UTC ISO 8601.
e_archive_url	string (nullable)	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.
carrier_shipping_code	string (nullable)	Tracking code assigned by the carrier.
shipping_company	string (enum & nullable)	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.
parent	integer or string (nullable)	The input must be the primary key value of an existing order item.
shipped_date	string (nullable)	The date when the order item was shipped. It must be formatted as UTC ISO 8601.
delivered_date	string (nullable)	The date when the order item was delivered. It must be formatted as UTC ISO 8601.
estimated_delivery_date	string (nullable)	The estimated delivery date for the order item. It must be formatted as YYYY-MM-DD.
defined_shipping_company	string (nullable)	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.
data_source	integer or string (nullable)	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.
shipping_option_group	integer or string (nullable)	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: Data Source Shipping Options and Attribute Based Shipping Options.

Key Points

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

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)

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

`PATCH` Update Order Statuses in Bulk

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

Parameter	Data Type	Description
id	id	Unique identifier for the order item.
invoice_number	string	The invoice number generated for the order item.
invoice_date	string	The date when the invoice was issued. The format is expected to follow ISO 8601 standards, e.g., `YYYY-MM-DDTHH:MM:SSZ`
e_archive_url	string	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.
status	string	The current status of the order item, mapped to Omnitron's predefined status codes. Allowed values are order status codes.
tracking_number	string	The tracking number provided by the shipping company for the order item.
shipping_company	enum	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.

Example Request

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)

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

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

PATCH Update Order​

Request Parameters​

Example Request​

Example Response (200 OK)​

Example Responses (400 Bad Request)​

PATCH Update Order Item​

Request Parameters​

Key Points​

Example Request​

Example Response (200 OK)​

Example Responses (400 Bad Request)​

PATCH Update Order Statuses in Bulk​

Request Parameters​

Example Request​

Example Response (200 OK)​

Example Responses (400 Bad Request)​

`PATCH` Update Order

Request Parameters

Example Request

Example Response (200 OK)

Example Responses (400 Bad Request)

`PATCH` Update Order Item

Request Parameters

Key Points

Example Request

Example Response (200 OK)

Example Responses (400 Bad Request)

`PATCH` Update Order Statuses in Bulk

Request Parameters

Example Request

Example Response (200 OK)

Example Responses (400 Bad Request)