> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/orders/order-items.md).

# Order Items

Administrative endpoints for **order items** — the individual line items of an order. An order item represents a single unit of one product within an order and carries its own status, price, tax rate, invoice data, shipping and tracking details, and free-form EAV attributes.

Order items are created by the checkout flow together with their parent order. These endpoints exist so that Omnitron and integration systems can read line items and push per-item fulfilment updates back into Commerce — status transitions, invoice numbers, tracking numbers, shipping companies, and shipped / delivered dates.

Because one order item represents exactly one unit, an order for three of the same product is stored as three separate order items. An item that was added to the basket as a child of another item — an add-on or bundled product, or a trade-in attached to a purchase — points at the order item it belongs to through `parent`, which is always another item of the same order.

### Core Capabilities

**1. Order Item Listing & Filtering**

* Retrieve a paginated list of order items, ordered by ascending identifier.
* Filter on almost every order-item field, and on the parent order's fields through `order__` traversal.
* Change the ordering with the `sort` parameter.

**2. Order Item Retrieval**

* Retrieve a single order item by its identifier.

**3. Order Item Creation**

* Create an order item on an existing order. Creation runs through the order service, which overwrites `extra_field` with a snapshot of the price-list and stock-list `extra_field` values and forces the item status to `300` (`payment_waiting`) when the parent order is in that status.

**4. Order Item Update**

* Partially update an order item — primarily to advance `status` and to write invoice, tracking, shipping and delivery data.
* Every successful update runs a set of per-item post-update actions (notifications, e-mail, SMS, subscription dispatch, basket-offer revocation) whose behaviour is controlled by the dynamic settings listed at the end of this section.

**5. Deletion is not allowed**

* `DELETE /order_items/{id}/` always fails with `406 Not Acceptable` and the error code `method_100`. Order items are never removed; cancel or refund an item by moving its `status` to `100` (`cancelled`) or `600` (`refunded`) instead.

### Request and Response Shapes

The read, create and update shapes are different objects and are **not** interchangeable:

| Operation                  | Request schema           | Response schema                                  |
| -------------------------- | ------------------------ | ------------------------------------------------ |
| `GET /order_items/`        | —                        | `PaginatedOrderItemList` (items are `OrderItem`) |
| `GET /order_items/{id}/`   | —                        | `OrderItem`                                      |
| `POST /order_items/`       | `OrderItemCreateRequest` | `OrderItemCreated`                               |
| `PUT /order_items/{id}/`   | `OrderItemUpdateRequest` | `OrderItem`                                      |
| `PATCH /order_items/{id}/` | `OrderItemPatchRequest`  | `OrderItem`                                      |

The read shape (`OrderItem`) identifies the record with `pk` and adds the parent product's `product_sku`, the nested `extra_product_price_detailed` / `extra_product_stock_detailed` / `datasource_detailed` objects, and the computed `discounted_price`. The create response (`OrderItemCreated`) identifies the record with `id` instead and exposes `order`, `created_date`, `modified_date` and the `localized_attributes` pair, but carries none of the nested detail objects and no `product_sku` or `discounted_price`. Do not assume that a field present in one shape exists in the other.

### Order Item Statuses

An order item's `status` moves independently of its parent order's status, which is what makes partial shipment and partial cancellation possible. Values are numeric strings from the same set the order uses.

| Value | Name                     | Description                                                                                                                                                                                                                                 |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `50`  | `cancellation_waiting`   | Cancellation has been requested for this item and is pending.                                                                                                                                                                               |
| `100` | `cancelled`              | The item has been cancelled.                                                                                                                                                                                                                |
| `200` | `waiting`                | The item has been created but payment has not yet been confirmed.                                                                                                                                                                           |
| `300` | `payment_waiting`        | Payment has been initiated and is waiting for confirmation.                                                                                                                                                                                 |
| `350` | `confirmation_waiting`   | The item is awaiting manual confirmation.                                                                                                                                                                                                   |
| `400` | `approved`               | Payment confirmed; the item is approved for fulfilment.                                                                                                                                                                                     |
| `430` | `waiting_for_substitute` | Waiting for a substitute product.                                                                                                                                                                                                           |
| `450` | `preparing`              | The item is being prepared / packed.                                                                                                                                                                                                        |
| `500` | `shipped`                | The item has been dispatched to the carrier.                                                                                                                                                                                                |
| `510` | `shipped_and_informed`   | The item has been shipped and the customer has been notified.                                                                                                                                                                               |
| `520` | `ready_for_pickup`       | The item is ready for in-store collection.                                                                                                                                                                                                  |
| `540` | `attempted_delivery`     | A delivery attempt was made but the recipient was unavailable.                                                                                                                                                                              |
| `544` | `review_started`         | A trade-in review has been started for the item.                                                                                                                                                                                            |
| `545` | `review_waiting`         | A trade-in review is waiting.                                                                                                                                                                                                               |
| `546` | `waiting_for_payment`    | Waiting for trade-in payment.                                                                                                                                                                                                               |
| `547` | `paid`                   | Trade-in payment received.                                                                                                                                                                                                                  |
| `550` | `delivered`              | The item has been delivered to the customer.                                                                                                                                                                                                |
| `600` | `refunded`               | The item has been refunded.                                                                                                                                                                                                                 |
| `700` | `merged`                 | Order-level value carried over from the shared status enum — it marks an add-on *order* that was merged into a main order. The platform does not set it on order items; it is accepted here only because items reuse the order status enum. |

### Update Semantics

* `PATCH` writes only the fields present in the request body; every other field keeps its current value. `modified_date` is always refreshed. Leaving `status` out means "do not change the status", and none of the status-gated post-update actions run.
* **`attributes` is merged, not replaced.** The submitted object is merged key by key into the stored one, so existing keys that are not mentioned survive and a key sent again is overwritten. There is no way to delete an attribute key through this endpoint.
* `attributes_kwargs` and `extra_field` are **replaced** with whatever is submitted. `localized_attributes` and `localized_attributes_kwargs` are not part of the update shape at all — they can be set at creation but are silently ignored on `PATCH`.
* `order` cannot be changed after creation — it is not part of the update shapes and is ignored if sent.
* **Status transition side effects.** When `status` changes while the item is still in `200` (`waiting`) or `300` (`payment_waiting`), the **unreported** sold-quantity counter (`sold_quantity_unreported`) on the item's stock record — its `extra_product_stock` when set, otherwise the product's own stock record — is decremented, marking the sale as reported. It is reduced by one for an ordinary item; for a product sold by weight it is reduced by the item's unit amount rounded up to whole units, and for a quantity-mergeable product by the unit amount stored on the item. It never goes below zero. After the item is saved, the post-update actions run — see **Post-Update Actions** below.
* **`PUT` and `PATCH` behave the same way, apart from which fields are required.** Both write only the fields present in the body — `PUT` does not reset the fields you leave out. `PUT` requires `product`, `status`, `price_currency`, `price` and `tax_rate`; `PATCH` requires nothing. Use `PATCH` unless you have a reason to send the full record.
* **`product_sku` is read-only** and is ignored on write, so a body read from `GET` can be sent straight back without stripping it. To point an item at a different product, send `product`; `product_sku` in the response then reflects the new product.
* `discount_amount` is validated against the item's `price`: it must be greater than or equal to `0` and less than or equal to `price`. `discounted_price` in the response is `price - discount_amount` and is computed, never stored.

### Post-Update Actions

The item is saved in its own transaction, and the post-update actions then run **synchronously, outside that transaction, before the response is returned**. Two consequences matter in practice: a slow gateway makes the request slow, and a failing action fails the request even though the item has already been saved and committed. Only the ready-for-pickup action swallows its own errors; the rest do not.

Which actions run depends on whether `status` actually changed — the handler compares the submitted `status` with the stored one:

| Action                                             | Runs when                                                                                                                                                                                                                          |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Partial shipping e-mail, SMS and push notification | `status` changed to `500` (`shipped`) **and** `tracking_number` is set **and** `SEND_SHIPPING_NOTIFICATIONS_PARTIALLY` is `true`.                                                                                                  |
| Partial delivery e-mail and push notification      | `status` changed to `550` (`delivered`) **and** `SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY` is `true`.                                                                                                                       |
| Per-item cancellation push notification            | `status` changed to `100` (`cancelled`) **and** `SEND_ORDER_CANCELLED_NOTIFICATIONS_PARTIALLY` is `true`.                                                                                                                          |
| Ready-for-pickup e-mail                            | `status` moved from `400` (`approved`) or `450` (`preparing`) to `520` (`ready_for_pickup`) **and** the order ships to a retail-store address. Errors are logged and swallowed.                                                    |
| Subscription (marketing) dispatch                  | `status` changed **and** `SUBSCRIPTION_ACTIVE` is `true`.                                                                                                                                                                          |
| Trade-in e-mail                                    | Every update while the item sits in `544` / `545` with an unresolved `inquiry` and `SEND_TRADEIN_MAIL_CASE` is `true` — **not** limited to status changes.                                                                         |
| Post-order basket-offer revocation                 | Every update while the item's `status` is `100` (`cancelled`) or `600` (`refunded`) and it is tied to a completed post-order action — **not** limited to status changes. Re-running it is a no-op once the offer has been revoked. |

Leaving `status` out of a `PATCH`, or re-sending the item's current value, both count as "unchanged": the status-gated actions in the table above are then skipped, while the last two still run.

### Filtering

A filter is available for every order-item field. Text fields match on a **case-insensitive partial match**, and the remaining fields match exactly:

| Parameters                                                                                                                                                                        | Match                                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`, `price_currency`, `shipping_company`, `defined_shipping_company`, `invoice_number`, `tracking_number`, `defined_tracking_url`, `e_archive_url`, `shipping_tracking_url` | Case-insensitive partial match. On the nullable ones, `NULL_VALUE` returns only records where the field is empty and `NOT_NULL_VALUE` only records where it is set. `status` and `price_currency` are never null, so `NULL_VALUE` returns an empty page for them. |
| `price`, `retail_price`, `tax_rate`, `discount_amount`                                                                                                                            | Exact numeric match.                                                                                                                                                                                                                                              |
| `product`, `parent`, `order`, `extra_product_price`, `extra_product_stock`, `datasource`, `shipping_option_group`                                                                 | Exact identifier match. An identifier that does not exist is rejected with `400`.                                                                                                                                                                                 |
| `created_date`, `modified_date`, `invoice_date`, `shipped_date`, `delivered_date`                                                                                                 | Exact ISO 8601 date-time match.                                                                                                                                                                                                                                   |
| `estimated_delivery_date`                                                                                                                                                         | Exact date match.                                                                                                                                                                                                                                                 |
| `image`                                                                                                                                                                           | Exact match on the stored file path.                                                                                                                                                                                                                              |
| `attributes`                                                                                                                                                                      | Filtered by JSON path — see **Filtering on `attributes`** below.                                                                                                                                                                                                  |
| `attributes_kwargs`, `localized_attributes`, `localized_attributes_kwargs`, `extra_field`                                                                                         | **Not usable** — see the note below `attributes`.                                                                                                                                                                                                                 |

**There is no `id` or `pk` filter.** To read a single item by its identifier use `GET /order_items/{id}/`.

**`status` is a substring match, not an exact one.** Because the status column stores numeric strings and the filter matches partially, `?status=50` also returns items whose status is `500` or `550`, and `?status=0` returns almost everything. Prefer a value that is not a prefix or infix of another status, or filter on the parent order instead.

**Parent order filters.** The parent order is traversable with a double underscore: `order__id`, `order__status` (exact), `order__number`, `order__user_email`, `order__is_payable`, `order__easy_return_code`, and `order__created_date` with the `__gt`, `__gte`, `__lt`, `__lte`, `__date__gt`, `__date__gte`, `__date__lt` and `__date__lte` lookups. `order=<id>` filters by the parent order's identifier directly.

**Negation.** Appending `!` to any filter parameter excludes the matching records instead of selecting them — `?status!=400` returns every item that is *not* approved.

**Filtering on `attributes`.** Address a key inside the item's EAV attributes with a double underscore — `?attributes__color=red`, or `?attributes__tax__total=12.00` for a nested key. The value is matched as a **case-insensitive substring** of the stored value's text form, so `?attributes__color=re` matches `red`.

| Form                                         | Meaning                                                                    |
| -------------------------------------------- | -------------------------------------------------------------------------- |
| `?attributes__<key>=<value>`                 | Case-insensitive substring match on that key.                              |
| `?attributes__<key>=<a>,<b>`                 | Several values for one key are **OR**-ed.                                  |
| `?attributes__<k1>=<a>&attributes__<k2>=<b>` | Different keys are **AND**-ed.                                             |
| `?attributes__<key>__exact=<value>`          | Exact match instead of a substring.                                        |
| `?attributes__<key>__isnull=true`            | Selects items where the key is absent; `false` selects items that have it. |

Three forms are **not supported** and must be avoided by the caller:

* **A value with no key path** (`?attributes=red`) — always address a key inside the field.
* **A path segment named after a query lookup** (`?attributes__color__gt=a`, `?attributes__color__icontains=red`) — the segment is resolved as that lookup rather than as a key. Only the `__exact` and `__isnull` suffixes are recognised; every other segment must be an actual key name.
* **The `!` exclusion suffix on a path** (`?attributes__color!=red`) — negation is resolved against filter names, not JSON paths, so `color!` is looked up as a key that does not exist and the page comes back empty. Do not read that as "no item matches".

The same applies to the other endpoints that filter on a JSON field, such as `/users/`.

**`attributes` is the only usable JSON filter.** `attributes_kwargs`, `localized_attributes`, `localized_attributes_kwargs` and `extra_field` are not wired up for path traversal, so do not send those parameters at all: their path form (`?extra_field__foo=x`) is not a filter name and is ignored like any unknown parameter, and the bare form (`?extra_field=x`) is not usable either.

**Unknown query parameters are ignored** rather than rejected.

### Sorting

Without a `sort` parameter, results come back ordered by ascending identifier. `sort` accepts a comma-separated list of fields; prefix a field with a hyphen for descending order.

Sortable fields: `pk`, `product`, `product__sku`, `status`, `price_currency`, `price`, `tax_rate`, `retail_price`, `discount_amount`, `invoice_number`, `invoice_date`, `e_archive_url`, `tracking_number`, `defined_tracking_url`, `shipping_company`, `defined_shipping_company`, `shipping_tracking_url`, `estimated_delivery_date`, `shipped_date`, `delivered_date`, `parent`, `extra_product_price`, `extra_product_stock`, `datasource`, `shipping_option_group`, `image`, `attributes`, `attributes_kwargs`, `extra_field`.

`discounted_price` is computed and cannot be sorted on; `created_date` and `modified_date` are not part of the read shape and are not sortable either. Unrecognised `sort` values are silently ignored rather than rejected.

### Dynamic Settings & Environment Variables

None of the settings below affect `GET` responses. They all take effect on the post-update actions that run after a successful `PATCH` (or `PUT`) of an order item; `POST` triggers none of them.

| Key                                               | Type             | Default                                                              | Effect on `PATCH`/`PUT`                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------- | ---------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SEND_SHIPPING_NOTIFICATIONS_PARTIALLY`           | boolean          | `false`                                                              | When `true`, moving an item's `status` to `500` (`shipped`) while its `tracking_number` is set schedules a partial-shipment e-mail, SMS and push notification for the parent order, debounced per order + shipping company + tracking number. When `false`, nothing is sent per item and the notification is instead sent once by `PUT`/`PATCH /orders/{id}/` when the whole order reaches `shipped`.                            |
| `SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY` | boolean          | `false`                                                              | When `true`, moving an item's `status` to `550` (`delivered`) schedules a partial-delivery e-mail and push notification. When `false`, delivery is announced once at order level.                                                                                                                                                                                                                                                |
| `SEND_ORDER_CANCELLED_NOTIFICATIONS_PARTIALLY`    | boolean          | `false`                                                              | When `true`, moving an item's `status` to `100` (`cancelled`) schedules a cancellation notification for the parent order, debounced per order so items cancelled together collapse into a single message. When `false`, the notification is sent once when the whole order is cancelled.                                                                                                                                         |
| `SEND_TRADEIN_MAIL_CASE`                          | boolean          | `false`                                                              | When `true` and the item carries an `inquiry` entry in `attributes` that has not yet been confirmed or rejected, an update leaves the item in `544` (`review_started`) or `545` (`review_waiting`) sends the matching trade-in e-mail. This action is **not** gated on the status actually changing, so a later update that only touches another field re-sends the e-mail while the item is still in one of those two statuses. |
| `SUBSCRIPTION_ACTIVE`                             | boolean          | `false`                                                              | When `true`, every `status` change dispatches the updated item to the configured subscription (marketing) gateway. When `false`, no dispatch happens.                                                                                                                                                                                                                                                                            |
| `SUBSCRIPTION_GATEWAY`                            | string / `null`  | `null`                                                               | Name of the subscription gateway the item update is dispatched to. Must match a key in `SUBSCRIPTION_GATEWAYS`.                                                                                                                                                                                                                                                                                                                  |
| `SUBSCRIPTION_GATEWAYS`                           | object           | `{}`                                                                 | Configuration map of the available subscription gateways. Keys are gateway names; values are gateway-specific config objects.                                                                                                                                                                                                                                                                                                    |
| `ACTIVE_SUBSCRIPTION_GATEWAYS`                    | array of strings | `[]`                                                                 | The subscription gateway names that actually receive the dispatch.                                                                                                                                                                                                                                                                                                                                                               |
| `NOTIFICATION_GATEWAY`                            | string           | `""`                                                                 | Name of the active push-notification gateway. While it is empty, every push notification triggered by an item update is silently skipped. Must match a key in `NOTIFICATION_GATEWAYS`.                                                                                                                                                                                                                                           |
| `NOTIFICATION_GATEWAYS`                           | object           | `{"console": {"conf": {}}}`                                          | Configuration map for the available push-notification gateways. Keys are gateway names; values are gateway-specific config objects.                                                                                                                                                                                                                                                                                              |
| `SMS_GATEWAY`                                     | string           | `"console"`                                                          | Name of the active SMS gateway used by the partial-shipment SMS. `"console"` logs to stdout without sending. Must match a key in `SMS_GATEWAYS`.                                                                                                                                                                                                                                                                                 |
| `SMS_GATEWAYS`                                    | object           | `{"console": {"conf": {"verify_message": "Verification code: {}"}}}` | Configuration map for the available SMS gateways. Keys are gateway names; values are gateway-specific config objects.                                                                                                                                                                                                                                                                                                            |
| `EMAIL_BCC_AND_CC`                                | object           | every e-mail template mapped to `{"bcc": [], "cc": []}`              | Per-template BCC and CC addresses for the e-mails sent by these actions. Keys are e-mail template names (`orders_partial_cargo`, `orders_partial_delivered_cargo`, `order_ready_for_pickup`); values are `{"bcc": [...], "cc": [...]}`.                                                                                                                                                                                          |
| `DISABLED_EMAIL_TEMPLATES`                        | object           | every template `false`, except `orders_preparing` which is `true`    | Per-template kill switch for outbound e-mail. When the template used by one of the actions above is set to `true`, that e-mail is skipped at send time while the SMS and push notification still go out.                                                                                                                                                                                                                         |
| `ORDERS_REFUNDABLE_DAYS`                          | integer / `null` | `null`                                                               | The number of days after ordering within which an item may be returned. Read by the order-item model but **not** exposed by these endpoints; it changes no request or response field here.                                                                                                                                                                                                                                       |

Every dynamic setting above falls back to the Django setting of the same name as its initial default, so a value set in the deployment's settings acts as the default until it is overridden in the dynamic-settings store.

**Environment variables:** No environment variables are read directly by these endpoints.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/orders/order-items.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
