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
- category[source]
Used by Google analytics tracking
- description[source]
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 overriden 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.
- shipping_event_breakdown[source]
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.
- shipping_status[source]
Returns a string summary of the shipping status of this line
- 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
- basket_total_before_discounts_excl_tax[source]
Return basket total excluding tax but before discounts are applied
- basket_total_before_discounts_incl_tax[source]
Return basket total including tax but before discounts are applied
- basket_total_excl_tax[source]
Return basket total excluding tax
- basket_total_incl_tax[source]
Return basket total including tax
- cascade = {'Cancelled': 'Cancelled', 'Complete': 'Shipped', 'Being processed': 'Being processed'}
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
- num_items[source]
Returns the number of items in this order.
- pipeline = {'Cancelled': (), 'Being processed': ('Complete', 'Cancelled'), 'Pending': ('Being processed', 'Cancelled'), 'Complete': ()}
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.
- set_status(new_status)[source]
Set a new status for this order.
If the requested status is not valid, then InvalidOrderStatus is raised.
- shipping_status[source]
Return the last complete shipping event for this order.
- total_discount_incl_tax[source]
The amount of discount this order received
- 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.
- 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/fulfillment event
Eg: ‘Shipped’, ‘Cancelled’, ‘Returned’
- class oscar.apps.order.abstract_models.PaymentEventQuantity(*args, **kwargs)[source]
A “through” model linking lines to payment events
- 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.
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.
- 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, line_quantities)[source]¶
Cancel the stock allocations for the passed lines
- consume_stock_allocations(order, lines, line_quantities)[source]¶
Consume the stock allocations for the passed 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 (ie 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, **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, **kwargs)[source]¶
Placing an order involves creating all the relevant models based on the basket and session data.