Offers

Oscar ships with a powerful and flexible offers engine which is contained in the offers app. It is based around the concept of ‘conditional offers’ - that is, a basket must satisfy some condition in order to qualify for a benefit.

Oscar’s dashboard can be used to administer offers.

Structure

A conditional offer is composed of several components:

  • Customer-facing information - this is the name and description of an offer. These will be visible on offer-browsing pages as well as within the basket and checkout pages.
  • Availability - this determines when an offer is available.
  • Condition - this determines when a customer qualifies for the offer (eg spend £20 on DVDs). There are various condition types available.
  • Benefit - this determines the discount a customer receives. The discount can be against the basket cost or the shipping for an order.

Availability

An offer’s availability can be controlled by several settings which can be used in isolation or combination:

  • Date range - a date can be set, outside of which the offer is unavailable.
  • Max global applications - the number of times and offer can be used can be capped. Note that an offer can be used multiple times within the same order so this isn’t the same as limiting the number of orders that can use an offer.
  • Max user applications - the number of times a particular user can use an offer. This makes most sense to use in sites that don’t allow anonymous checkout as it could be circumvented by submitting multiple anonymous orders.
  • Max basket applications - the number of times an offer can be used for a single basket/order.
  • Max discount - the maximum amount of discount an offer can give across all orders. For instance, you might have a marketing budget of £10000 and so you could set the max discount to this value to ensure that once £10000 worth of benefit had been awarded, the offer would no longer be available. Note that the total discount would exceed £10000 as it would have to cross this threshold to disable the offer.

Conditions

There are 3 built-in condition types that can be created via the dashboard. Each needs to be linked with a range object, which is subset of the product catalogue. Ranges are created independently in the dashboard.

  • Count-based - ie a customer must buy X products from the condition range
  • Coverge-based - ie a customer must buy X DISTINCT products from the condition range. This can be used to create “bundle” offers.
  • Value-based - ie a customer must spend X on products from the condition range

It is also possible to create custom conditions in Python and register these so they are available to be selected within the dashboard. For instance, you could create a condition that specifies that the user must have been registered for over a year to qualify for the offer.

Under the hood, conditions are defined by 3 attributes: a range, a type and a value.

Benefits

There are several types of built-in benefit, which fall into one of two categories: benefits that give a basket discount, and those that give a shipping discount.

Basket benefits:

  • Fixed discount - ie get £5 off DVDs
  • Percentage discount - ie get 25% off books
  • Fixed price - ie get any DVD for £8
  • Multibuy - ie get the cheapest product that meets the condition for free

Shipping benefits (these largely mirror the basket benefits):

  • Fixed discount - ie £5 off shipping
  • Percentage discount - ie get 25% off shipping
  • Fixed price - ie get shipping for £8

Like conditions, it is possible to create a custom benefit. An example might be to allow customers to earn extra credits/points when they qualify for some offer. For example, spend £100 on perfume, get 500 credits (note credits don’t exist in core Oscar but can be implemented using the ‘accounts’ plugin).

Under the hood, benefits are modelled by 4 attributes: a range, a type, a value and a setting for the maximum number of basket items that can be affected by a benefit. This last settings is useful for limiting the scope of an offer. For instance, you can create a benefit that gives 40% off ONE products from a given range by setting the max affected items to 1. Without this setting, the benefit would give 40% off ALL products from the range.

Benefits are slightly tricky in that some types don’t require a range and ignore the value of the max items setting.

Examples

Here’s some example offers:

3 for 2 on books
  1. Create a range for all books.
  2. Use a count-based condition that links to this range with a value of 3.
  3. Use a multibuy benefit with no value (the value is implicitly 1)
Spend £20 on DVDs, get 25% off
  1. Create a range for all DVDs.
  2. Use a value-based condition that links to this range with a value of 20.
  3. Use a percentage discount benefit that links to this range and has a value of 25.
Buy 2 Lonely Planet books, get £5 off a Lonely Planet DVD
  1. Create a range for Lonely Planet books and another for Lonely Planet DVDs
  2. Use a count-based condition linking to the book range with a value of 2
  3. Use a fixed discount benefit that links to the DVD range and has a value of 5.

More to come...

Abstract models

class oscar.apps.offer.abstract_models.AbstractCondition(*args, **kwargs)[source]

A condition for an offer to be applied. You can either specify a custom proxy class, or need to specify a type, range and value.

can_apply_condition(line)[source]

Determines whether the condition can be applied to a given basket line

description[source]

A description of the condition. Defaults to the name. May contain HTML.

get_applicable_lines(offer, basket, most_expensive_first=True)[source]

Return line data for the lines that can be consumed by this condition

is_partially_satisfied(offer, basket)[source]

Determine if the basket partially meets the condition. This is useful for up-selling messages to entice customers to buy something more in order to qualify for an offer.

is_satisfied(offer, basket)[source]

Determines whether a given basket meets this condition. This is stubbed in this top-class object. The subclassing proxies are responsible for implementing it correctly.

name[source]

A plaintext description of the condition. Every proxy class has to implement it.

This is used in the dropdowns within the offer dashboard.

proxy()[source]

Return the proxy model

class oscar.apps.offer.abstract_models.AbstractConditionalOffer(*args, **kwargs)[source]

A conditional offer (eg buy 1, get 10% off)

apply_benefit(basket)[source]

Applies the benefit to the given basket and returns the discount.

apply_deferred_benefit(basket, order, application)[source]

Applies any deferred benefits. These are things like adding loyalty points to somone’s account.

availability_description()[source]

Return a description of when this offer is available

get_max_applications(user=None)[source]

Return the number of times this offer can be applied to a basket for a given user.

is_available(user=None, test_date=None)[source]

Test whether this offer is available to be used

products()[source]

Return a queryset of products in this offer

class oscar.apps.offer.abstract_models.AbstractRange(*args, **kwargs)[source]

Represents a range of products that can be used within an offer.

Ranges only support adding parent or stand-alone products. Offers will consider child products automatically.

add_product(product, display_order=None)[source]

Add product to the range

When adding product that is already in the range, prevent re-adding it. If display_order is specified, update it.

Default display_order for a new product in the range is 0; this puts the product at the top of the list.

all_products()[source]

Return a queryset containing all the products in the range

This includes included_products plus the products contained in the included classes and categories, minus the products in excluded_products.

contains(product)

Check whether the passed product is part of this range.

contains_product(product)[source]

Check whether the passed product is part of this range.

is_editable[source]

Test whether this product can be edited in the dashboard

remove_product(product)[source]

Remove product from range. To save on queries, this function does not check if the product is in fact in the range.

class oscar.apps.offer.abstract_models.AbstractRangeProduct(*args, **kwargs)[source]

Allow ordering products inside ranges Exists to allow customising.

Models

class oscar.apps.offer.models.BasketDiscount(amount)

For when an offer application leads to a simple discount off the basket’s total

class oscar.apps.offer.models.ShippingDiscount

For when an offer application leads to a discount from the shipping cost

class oscar.apps.offer.models.PostOrderAction(description)

For when an offer condition is met but the benefit is deferred until after the order has been placed. Eg buy 2 books and get 100 loyalty points.

class oscar.apps.offer.models.ConditionalOffer(*args, **kwargs)[source]

ConditionalOffer(id, name, slug, description, offer_type, status, condition, benefit, priority, start_datetime, end_datetime, max_global_applications, max_user_applications, max_basket_applications, max_discount, total_discount, num_applications, num_orders, redirect_url, date_created)

class oscar.apps.offer.models.Benefit(*args, **kwargs)[source]

Benefit(id, range, type, value, max_affected_items, proxy_class)

class oscar.apps.offer.models.Condition(*args, **kwargs)[source]

Condition(id, range, type, value, proxy_class)

class oscar.apps.offer.models.Range(*args, **kwargs)[source]

Range(id, name, slug, description, is_public, includes_all_products, proxy_class, date_created)

class oscar.apps.offer.models.RangeProduct(*args, **kwargs)[source]

RangeProduct(id, range, product, display_order)

class oscar.apps.offer.models.RangeProductFileUpload(*args, **kwargs)[source]

RangeProductFileUpload(id, range, filepath, size, uploaded_by, date_uploaded, status, error_message, date_processed, num_new_skus, num_unknown_skus, num_duplicate_skus)

class oscar.apps.offer.models.PercentageDiscountBenefit(*args, **kwargs)

An offer benefit that gives a percentage discount

class oscar.apps.offer.models.AbsoluteDiscountBenefit(*args, **kwargs)

An offer benefit that gives an absolute discount

class oscar.apps.offer.models.FixedPriceBenefit(*args, **kwargs)

An offer benefit that gives the items in the condition for a fixed price. This is useful for “bundle” offers.

Note that we ignore the benefit range here and only give a fixed price for the products in the condition range. The condition cannot be a value condition.

We also ignore the max_affected_items setting.

class oscar.apps.offer.models.ShippingBenefit(*args, **kwargs)

ShippingBenefit(id, range, type, value, max_affected_items, proxy_class)

class oscar.apps.offer.models.MultibuyDiscountBenefit(*args, **kwargs)

MultibuyDiscountBenefit(id, range, type, value, max_affected_items, proxy_class)

class oscar.apps.offer.models.ShippingAbsoluteDiscountBenefit(*args, **kwargs)

ShippingAbsoluteDiscountBenefit(id, range, type, value, max_affected_items, proxy_class)

class oscar.apps.offer.models.ShippingFixedPriceBenefit(*args, **kwargs)

ShippingFixedPriceBenefit(id, range, type, value, max_affected_items, proxy_class)

class oscar.apps.offer.models.ShippingPercentageDiscountBenefit(*args, **kwargs)

ShippingPercentageDiscountBenefit(id, range, type, value, max_affected_items, proxy_class)

class oscar.apps.offer.models.CountCondition(*args, **kwargs)

An offer condition dependent on the NUMBER of matching items from the basket.

consume_items(offer, basket, affected_lines)

Marks items within the basket lines as consumed so they can’t be reused in other offers.

Basket:The basket
Affected_lines:The lines that have been affected by the discount. This should be list of tuples (line, discount, qty)
is_satisfied(offer, basket)

Determines whether a given basket meets this condition

class oscar.apps.offer.models.CoverageCondition(*args, **kwargs)

An offer condition dependent on the number of DISTINCT matching items from the basket.

consume_items(offer, basket, affected_lines)

Marks items within the basket lines as consumed so they can’t be reused in other offers.

is_satisfied(offer, basket)

Determines whether a given basket meets this condition

class oscar.apps.offer.models.ValueCondition(*args, **kwargs)

An offer condition dependent on the VALUE of matching items from the basket.

consume_items(offer, basket, affected_lines)

Marks items within the basket lines as consumed so they can’t be reused in other offers.

We allow lines to be passed in as sometimes we want them sorted in a specific order.

is_satisfied(offer, basket)

Determine whether a given basket meets this condition

Views