Order¶
The order app handles processing of orders.
Abstract models¶
-
class
oscar.apps.order.abstract_models.
AbstractCommunicationEvent
(*args, **kwargs)[source] An order-level event involving a communication to the customer, such as an confirmation email being sent.
-
class
oscar.apps.order.abstract_models.
AbstractLine
(*args, **kwargs)[source] An order line
-
classmethod
all_statuses
()[source] Return all possible statuses for an order line
-
available_statuses
()[source] Return all possible statuses that this order line can move to
-
property
description
Returns a description of this line including details of any line attributes.
-
get_event_quantity
(event)[source] Fetches the ShippingEventQuantity instance for this line
Exists as a separate method so it can be overridden to avoid the DB query that’s caused by get().
-
has_shipping_event_occurred
(event_type, quantity=None)[source] Test whether this line has passed a given shipping event
-
is_available_to_reorder
(basket, strategy)[source] Test if this line can be re-ordered using the passed strategy and basket
-
is_payment_event_permitted
(event_type, quantity)[source] Test whether a payment event with the given quantity is permitted.
Allow each payment event type to occur only once per quantity.
-
is_shipping_event_permitted
(event_type, quantity)[source] Test whether a shipping event with the given quantity is permitted
This method should normally be overridden to ensure that the prerequisite shipping events have been passed for this line.
-
payment_event_quantity
(event_type)[source] Return the quantity of this line that has been involved in a payment event of the passed type.
-
pipeline
= {} Order status pipeline. This should be a dict where each (key, value) corresponds to a status and the possible statuses that can follow that one.
-
set_status
(new_status)[source] Set a new status for this line
If the requested status is not valid, then
InvalidLineStatus
is raised.
-
property
shipping_event_breakdown
Returns a dict of shipping events that this line has been through
-
shipping_event_quantity
(event_type)[source] Return the quantity of this line that has been involved in a shipping event of the passed type.
-
property
shipping_status
Returns a string summary of the shipping status of this line
-
classmethod
-
class
oscar.apps.order.abstract_models.
AbstractLineAttribute
(*args, **kwargs)[source] An attribute of a line
-
class
oscar.apps.order.abstract_models.
AbstractLinePrice
(*args, **kwargs)[source] For tracking the prices paid for each unit within a line.
This is necessary as offers can lead to units within a line having different prices. For example, one product may be sold at 50% off as it’s part of an offer while the remainder are full price.
-
class
oscar.apps.order.abstract_models.
AbstractOrder
(*args, **kwargs)[source] The main order model
-
classmethod
all_statuses
()[source] Return all possible statuses for an order
-
available_statuses
()[source] Return all possible statuses that this order can move to
-
property
basket_total_before_discounts_excl_tax
Return basket total excluding tax but before discounts are applied
-
property
basket_total_before_discounts_incl_tax
Return basket total including tax but before discounts are applied
-
property
basket_total_excl_tax
Return basket total excluding tax
-
property
basket_total_incl_tax
Return basket total including tax
-
cascade
= {'Being processed': 'Being processed', 'Cancelled': 'Cancelled', 'Complete': 'Shipped'} Order status cascade pipeline. This should be a dict where each (key, value) pair corresponds to an order status and the corresponding line status that needs to be set when the order is set to the new status
-
check_verification_hash
(hash_to_check)[source] Checks the received verification hash against this order number. Returns False if the verification failed, True otherwise.
-
property
num_items
Returns the number of items in this order.
-
pipeline
= {'Being processed': ('Complete', 'Cancelled'), 'Cancelled': (), 'Complete': (), 'Pending': ('Being processed', 'Cancelled')} Order status pipeline. This should be a dict where each (key, value) #: corresponds to a status and a list of possible statuses that can follow that one.
-
save
(*args, **kwargs)[source] Save the current instance. Override this in a subclass if you want to control the saving process.
The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.
-
set_status
(new_status)[source] Set a new status for this order.
If the requested status is not valid, then
InvalidOrderStatus
is raised.
-
property
shipping_status
Return the last complete shipping event for this order.
-
property
total_discount_incl_tax
The amount of discount this order received
-
classmethod
-
class
oscar.apps.order.abstract_models.
AbstractOrderDiscount
(*args, **kwargs)[source] A discount against an order.
Normally only used for display purposes so an order can be listed with discounts displayed separately even though in reality, the discounts are applied at the line level.
This has evolved to be a slightly misleading class name as this really track benefit applications which aren’t necessarily discounts.
-
save
(**kwargs)[source] Save the current instance. Override this in a subclass if you want to control the saving process.
The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.
-
-
class
oscar.apps.order.abstract_models.
AbstractOrderNote
(*args, **kwargs)[source] A note against an order.
This are often used for audit purposes too. IE, whenever an admin makes a change to an order, we create a note to record what happened.
-
class
oscar.apps.order.abstract_models.
AbstractPaymentEvent
(*args, **kwargs)[source] A payment event for an order
For example:
All lines have been paid for
2 lines have been refunded
-
class
oscar.apps.order.abstract_models.
AbstractPaymentEventType
(*args, **kwargs)[source] Payment event types are things like ‘Paid’, ‘Failed’, ‘Refunded’.
These are effectively the transaction types.
-
class
oscar.apps.order.abstract_models.
AbstractShippingEvent
(*args, **kwargs)[source] An event is something which happens to a group of lines such as 1 item being dispatched.
-
class
oscar.apps.order.abstract_models.
AbstractShippingEventType
(*args, **kwargs)[source] A type of shipping/fulfilment event
E.g.: ‘Shipped’, ‘Cancelled’, ‘Returned’
-
class
oscar.apps.order.abstract_models.
PaymentEventQuantity
(*args, **kwargs)[source] A “through” model linking lines to payment events
-
exception
DoesNotExist
-
exception
MultipleObjectsReturned
-
exception
-
class
oscar.apps.order.abstract_models.
ShippingEventQuantity
(*args, **kwargs)[source] A “through” model linking lines to shipping events.
This exists to track the quantity of a line that is involved in a particular shipping event.
-
exception
DoesNotExist
-
exception
MultipleObjectsReturned
-
save
(*args, **kwargs)[source] Save the current instance. Override this in a subclass if you want to control the saving process.
The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.
-
exception
Order processing¶
-
class
oscar.apps.order.processing.
EventHandler
(user=None)[source]¶ Handle requested order events.
This is an important class: it houses the core logic of your shop’s order processing pipeline.
-
are_stock_allocations_available
(lines, line_quantities)[source]¶ Check whether stock records still have enough stock to honour the requested allocations.
Lines whose product doesn’t track stock are disregarded, which means this method will return True if only non-stock-tracking-lines are passed. This means you can just throw all order lines to this method, without checking whether stock tracking is enabled or not. This is okay, as calling consume_stock_allocations() has no effect for non-stock-tracking lines.
-
calculate_payment_event_subtotal
(event_type, lines, line_quantities)[source]¶ Calculate the total charge for the passed event type, lines and line quantities.
This takes into account the previous prices that have been charged for this event.
Note that shipping is not including in this subtotal. You need to subclass and extend this method if you want to include shipping costs.
-
cancel_stock_allocations
(order, lines=None, line_quantities=None)[source]¶ Cancel the stock allocations for the passed lines.
If no lines/quantities are passed, do it for all lines.
-
consume_stock_allocations
(order, lines=None, line_quantities=None)[source]¶ Consume the stock allocations for the passed lines.
If no lines/quantities are passed, do it for all lines.
-
handle_order_status_change
(order, new_status, note_msg=None)[source]¶ Handle a requested order status change
This method is not normally called directly by client code. The main use-case is when an order is cancelled, which in some ways could be viewed as a shipping event affecting all lines.
-
handle_payment_event
(order, event_type, amount, lines=None, line_quantities=None, **kwargs)[source]¶ Handle a payment event for a given order.
These should normally be called as part of handling a shipping event. It is rare to call to this method directly. It does make sense for refunds though where the payment event may be unrelated to a particular shipping event and doesn’t directly correspond to a set of lines.
-
handle_shipping_event
(order, event_type, lines, line_quantities, **kwargs)[source]¶ Handle a shipping event for a given order.
This is most common entry point to this class - most of your order processing should be modelled around shipping events. Shipping events can be used to trigger payment and communication events.
You will generally want to override this method to implement the specifics of you order processing pipeline.
-
have_lines_passed_shipping_event
(order, lines, line_quantities, event_type)[source]¶ Test whether the passed lines and quantities have been through the specified shipping event.
This is useful for validating if certain shipping events are allowed (i.e. you can’t return something before it has shipped).
-
Utils¶
-
class
oscar.apps.order.utils.
OrderCreator
[source]¶ Places the order by writing out the various models
-
create_additional_line_models
(order, order_line, basket_line)[source]¶ Empty method designed to be overridden.
Some applications require additional information about lines, this method provides a clean place to create additional models that relate to a given line.
-
create_discount_model
(order, discount)[source]¶ Create an order discount model for each offer application attached to the basket.
-
create_line_models
(order, basket_line, extra_line_fields=None)[source]¶ Create the batch line model.
You can set extra fields by passing a dictionary as the extra_line_fields value
-
create_line_price_models
(order, order_line, basket_line)[source]¶ Creates the batch line price models
-
create_order_model
(user, basket, shipping_address, shipping_method, shipping_charge, billing_address, total, order_number, status, request=None, surcharges=None, **extra_order_fields)[source]¶ Create an order model.
-
place_order
(basket, total, shipping_method, shipping_charge, user=None, shipping_address=None, billing_address=None, order_number=None, status=None, request=None, surcharges=None, **kwargs)[source]¶ Placing an order involves creating all the relevant models based on the basket and session data.
-