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]

A order line (basically a product and a quantity)

Not using a line model as it’s difficult to capture and payment information when it splits across a 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.

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

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 = {}

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': ('Processed', 'Cancelled'), 'Pending': ('Being processed', 'Cancelled'), 'Processed': ()}

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.

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

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, billing_address, total, order_number, status, **extra_order_fields)[source]

Creates an order model.

place_order(basket, total, user=None, shipping_method=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.

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