User Orders & Cancellations
GET List User Orders
This endpoint allows an authenticated user to retrieve a list of all their orders..
Path: /users/orders/
Authentication Required: Yes
Headers:
Accept-Language: <iso_language_code>
Cookie: <cookie-name>=<session_id>Query Parameters
status
string (repeatable)
No
Filter by one or more order statuses. Accepted values: 50 (cancellation_waiting), 100 (cancelled), 200 (waiting), 300 (payment_waiting), 350 (confirmation_waiting), 400 (approved), 430 (waiting_for_substitute), 450 (preparing), 500 (shipped), 510 (shipped_and_informed), 520 (ready_for_pickup), 540 (attempted_delivery), 544 (review_started), 545 (review_waiting), 546 (waiting_for_payment), 547 (paid), 550 (delivered), 600 (refunded), 700 (merged). Example: ?status=100&status=600
cancellation_type
string (repeatable)
No
Filter orders that have cancellation requests of the given type(s). Accepted values: cancel, refund. Example: ?cancellation_type=cancel&cancellation_type=refund
currency
string
No
Filter by currency code. Accepted values: try, eur, usd, egp, gbp, mad, pln, sar, ron, uah, czk, huf, rub, bgn, iqd, kwd, bhd, omr, qar, aed, ngn, inr, lei, kzt, jod, rsd, amd, cfa, lyd.
shipping_option_id
integer
No
Filter by shipping option ID.
shipping_option_slug
string
No
Filter by shipping option slug (partial match).
last_month
boolean
No
If true, returns only orders from the last 30 days.
search
string
No
Search by order number.
page
integer
No
Page number for pagination.
Example Request
import requests
url = "https://{commerce_url}/users/orders/"
headers = {
'Accept-Language': '<iso_language_code>',
'Cookie': '<cookie-name>=<session_id>'
}
response = requests.get(url, headers=headers)
print(response.text)Example Response (200 OK)
GET Retrieve User Order
This endpoint allows you to retrieve detailed information about a specific user's order using the order ID (<pk>).
Path: /users/orders/<pk>/
Authentication Required: Yes
Headers:
Example Request
Example Response (200 OK)
GET Display Return Items for Order Cancellation
This endpoint is used to list and display the return items for a specific order on the shop page, showing information about cancelled items and their details.
Path: /users/orders/<pk>/cancellation/
Authentication Required: Yes
Headers:
Example Request
Example Response (200 OK)
POST User Bulk Create Cancellation Requests
This endpoint allows for creating cancellation requests for multiple orders at once.
Path: /users/orders/bulk_cancellation_requests/
Authentication Required: Yes
Headers:
Body Parameters
cancel_order_items.cancellation_type
enum
True
Type of cancellations. Possible values are “cancel” and “refund”.
cancel_order_items.quantity
integer
False
Specifies the quantity of the order items that are to be cancelled. This field is optional and can be left empty unless a specific quantity is required for the cancellation.
cancel_order_items.description
string
False
An optional description or message explaining the reason for cancellation.
cancel_order_items.order_item
integer
True
The ID of the order item to be cancelled.
cancel_order_items.shipping_company
integer
False
The ID of the Shipping Company (if applicable).
cancel_order_items.iban
String
False
The IBAN number for the refund (if applicable).
cancel_order_items.holder_name
String
False
The name of the account holder for refunding (if applicable).
cancel_order_items.pickup_date.date
date
False
Represents the specific date for the pickup of the cancelled order item. This field is expected to follow a date format (e.g., YYYY-MM-DD).
cancel_order_items.pickup_date.hour_range.start
string
False
Indicates the starting time of the pickup window, usually in the format of HH:MM (e.g., "09:00").
cancel_order_items.pickup_date.hour_range.end
string
False
Represents the ending time of the pickup window, usually in the format of HH:MM (e.g., "12:00").
pickup_address
Integer
False
The ID of the address where the item should be picked up for return.
fully_refund_as_loyalty_money
Boolean
False
Indicates whether the refund should be processed as loyalty money.
Request Body
Example Request
Example Response (201 Created)
GET List User Order Cancellation Reasons
This endpoint retrieves a list of cancellation reasons associated with user orders. Cancellation reasons define why an order or item was canceled or returned, such as receiving the wrong product, changing one's mind, or other reasons. This can help in processing and managing cancellations more effectively.
Path: /users/orders/cancellation_reasons/
Authentication Required: Yes
Headers:
Example Request
Example Response (200 OK)
Body Parameters
cancellation_type
Enum
The type of cancellation. Possible values are: “cancel” and “refund”.
translations
Dict
Translations for the subject of the cancellation reason in different languages.
uuid
String
A unique identifier (UUID) for the cancellation reason.
subject
String
The subject of the cancellation reason, which describes why the order or product is being canceled.
extra_information_needed
Boolean
Indicates if any additional information is needed from the user to process the cancellation
order
Integer
The ID of the order that this cancellation reason is associated with.
GET List User Order Cancellation Requests
This endpoint is used to retrieve a list of order cancellation requests for a user. Each cancellation request includes details like the reason for cancellation, the status of the request, and any related order details.
Path: /users/orders/cancellation_requests/
Authentication Required: Yes
Headers:
Example Request
Example Response (200 OK)
POST Create User Order Cancellation Request
This endpoint is used to create a new cancellation request for an order item. Users can request either a full cancellation of the order or a refund for the order item, with additional options for specifying shipping logistics, refund details, and the reason for the cancellation.
Path: /users/orders/cancellation_requests/
Authentication Required: Yes
Headers:
Body Parameters
cancellation_type
Enum
True
Indicates the type of cancellation: "cancel" for order cancellation, "refund" for refund request.
reason
Integer
True
The ID of the cancellation reason.
order_item
Integer
True
The ID of the order item being canceled.
shipping_company
Integer
False
The ID of the shipping company handling the return, if applicable.
pickup_address
Integer
False
The ID of the address where the item should be picked up for return.
pickup_date
Dict
False
The scheduled date and time for pickup of the returned item. Includes date and hour_range (start and end times). { "date": "2024-01-01", "hour_range": { "start": "09:00", "end": "12:00" } }
quantity
Integer
False
The number of items to be canceled (should not exceed the quantity ordered).
description
String
False
An optional description or message explaining the reason for cancellation.
iban
String
False
The IBAN number for the refund (if applicable).
holder_name
String
False
The name of the account holder for refunding (if applicable).
fully_refund_as_loyalty_money
Boolean
False
Indicates whether the refund should be processed as loyalty money.
Request Body
Example Request
Example Response (200 OK)
Example Response (406 Not Acceptable)
If the pickup_address is not provided:
Example Response (400 Bad Request)
If the quantity is provided and is greater than the available quantity of the order item
GET Retrieve User’s All Old Orders
This endpoint retrieves a list of previously placed orders for a user.
Path: /users/old-orders/
Authentication Required: Yes
Headers:
Example Request
Example Response (200 OK)
GET Retrieve User’s Old Order
This endpoint retrieves the details of a specific previously placed order.
Path: /users/old-orders/<pk>/
Authentication Required: Yes
Headers:
Example Request
Example Response (200 OK)
GET Approve Trade-in
This endpoint confirms the approval of a trade offer for an item. The URL is sent via email, and clicking it confirms the trade.
Path: /users/order_item/<pk>/tradein_approved/
Authentication Required: Yes
Headers:
Example Request
Example Response (200 OK)
GET Reject Trade-in
This endpoint rejects a trade offer made for an item. The URL is sent to the user via email, and clicking the link confirms the rejection of the trade.
Path: /users/order_item/<pk>/tradein_rejected/
Authentication Required: No
Headers:
Example Request
Example Response (200 OK)
POST Direct Order Cancel
This endpoint directly cancels selected order items and sends the cancellation to Omnitron. It supports both authenticated and guest (anonymous) users.
Path: /orders/{order_number}/cancel/
Authentication Required: Optional — session cookie for authenticated users, email in request body for guest users.
Headers (Authenticated User)
Headers (Guest User)
Body Parameters
String
No*
Required for guest users. Must match the email address used when placing the order.
cancel_order_items
Array
True
List of order items to cancel.
cancel_order_items.order_item
Integer
True
The ID of the order item to cancel.
cancel_order_items.cancellation_type
Enum
True
Type of cancellation. Possible values are cancel and refund.
cancel_order_items.reason
Integer
True
The ID of the cancellation reason.
cancel_order_items.description
String
False
An optional message explaining the reason for the cancellation.
cancel_order_items.quantity
Integer
False
Specifies the quantity to cancel. If not provided, all items are cancelled.
cancel_order_items.iban
String
False
IBAN number for refund processing (if applicable).
cancel_order_items.holder_name
String
False
Name of the account holder for refunding (if applicable).
cancel_order_items.shipping_company
Integer
False
The ID of the shipping company (if applicable).
cancel_order_items.pickup_date
Object
False
Scheduled pickup date and time. { "date": "2024-01-01", "hour_range": { "start": "09:00", "end": "12:00" } }
pickup_address
Integer
False
Address ID for product pickup (for refund requests with easy return). Not available for guest users.
fully_refund_as_loyalty_money
Boolean
False
If true, the refund will be processed as loyalty points.
* email is required only for guest users. If not provided and the user is not authenticated, the endpoint returns 401 Unauthorized. Authenticated users do not need to provide it.
How It Works:
Authenticated users: The order must belong to the logged-in user. Ownership is validated via session.
Guest users: The
emailfield must be provided and must match the email address used when placing the order.
If the direct cancellation to Omnitron succeeds, the endpoint returns 204 No Content and the order item statuses are updated to cancellation_waiting. If the direct cancellation fails for any reason (e.g. Omnitron API error, validation rules), the system automatically creates local CancellationRequest records as a fallback and returns 200 OK. If the fallback also fails (e.g. item already cancelled, item status not allowed), the endpoint returns 406 Not Acceptable.
Cancellable Order Statuses (Default):
payment_waitingconfirmation_waitingapproved
Request Body (Authenticated User)
Request Body (Guest User)
Example Request (Authenticated User)
Example Request (Guest User)
Example Response (204 No Content)
Direct cancellation successful. No response body.
Example Response (200 OK)
Direct cancellation failed (e.g. Omnitron API error, validation rules). Local CancellationRequest records created as fallback.
Example Response (400 Bad Request)
Guest email does not match the order email:
Guest order number not found (or belongs to a registered user):
Serializer validation error (e.g. invalid order item):
Example Response (401 Unauthorized)
No email provided and user is not authenticated:
Example Response (404 Not Found)
Authenticated user: order not found or does not belong to the logged-in user:
Example Response (406 Not Acceptable)
Item already cancelled:
Item status not allowed:
Duplicate order items:
IBAN required (refund with certain payment methods):
Description required:
Last updated
Was this helpful?