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)

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"
        }
    }
]
PreviousOrders Waiting to Send to ERPNextStock Reservation Release

Last updated

Was this helpful?