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

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

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
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.

Order processing

class oscar.apps.order.processing.EventHandler(user=None, **kwargs)[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).

validate_shipping_event(order, event_type, lines, line_quantities, **kwargs)[source]

Test if the requested shipping event is permitted.

If not, raise InvalidShippingEvent

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_attributes(order, order_line, basket_line)[source]

Creates the batch line attributes.

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.

record_voucher_usage(order, voucher, user)[source]

Updates the models that care about this voucher.

update_stock_records(line)[source]

Update any relevant stock records for this order line

class oscar.apps.order.utils.OrderDispatcher(logger=None, mail_connection=None)[source]

Dispatcher to send concrete order related emails.

create_communication_event(order, event_type, dispatched_messages)[source]

Create order communications event for audit.

dispatch_order_messages(order, messages, event_code, attachments=None, **kwargs)[source]

Dispatch order-related messages to the customer.

class oscar.apps.order.utils.OrderNumberGenerator[source]

Simple object for generating order numbers.

We need this as the order number is often required for payment which takes place before the order model has been created.

order_number(basket)[source]

Return an order number for a given basket