Implementation of Prices and Taxes in Shoop

This document describes deeper details about price and tax implementation in Shoop from a developer’s point of view. To understand the basics, please read Prices and Taxes in Shoop first.

Types Used for Prices and Taxes

Money

Used to represent money amounts (that are not prices). It is basically a Decimal number with a currency.

Price

Used to represent prices. Price is a Money with an includes_tax property. It has has two subclasses: TaxfulPrice and TaxlessPrice.

There should usually be no need to create prices directly with these classes; see Creating Prices.

Priceful

An interface for accessing the price information of a product, order line, basket line, or whatever. See Accessing Prices of Product or Line.

PriceInfo

A class for describing an item’s price information.

PricingModule

An interface for querying prices of products.

PricingContext

A container for variables that affect pricing. Pricing modules may subclass this.

PricingContextable

An interface for objects that can be converted to a pricing context. Instances of PricingContext or HttpRequest satisfy this interface.

LineTax

An interface for describing a calculated tax of a line in order or basket. Has a reference to the line and to the applied tax and the calculated amount of tax. One line could have several taxes applied, each is presented with a separate LineTax.

SourceLineTax

A container for a calculated tax of a SourceLine (or BasketLine). Implements the LineTax interface.

OrderLineTax

A Django model for persistently storing the calculated tax of an OrderLine. Implements the LineTax interface.

Tax

A Django model for a tax with name, code, and percentage rate or fixed amount. Fixed amounts are not yet supported.

Todo

Fix this when fixed amounts are supported.

TaxableItem

An interface for items that can be taxed. Implemented by Product, ShippingMethod, PaymentMethod and SourceLine.

TaxClass

A Django model for a tax class. Taxable items (e.g. products, methods or lines) are grouped to tax classes to make it possible to have different taxation rules for different groups of items.

CustomerTaxGroup

A Django model for grouping customers to make it possible to have different taxation rules for different groups of customers. Shoop assigns separate CustomerTaxGroup`s for a `~shoop.core.models.PersonContact and a CompanyContact by default.

TaxModule

An interface for calculating the taxes of an OrderSource or any TaxableItem. The Shoop Base distribution ships a concrete implementation of a TaxModule called DefaultTaxModule. It is a based on a table of tax rules (saved with TaxRule model). See The Default Tax Module. Used TaxModule can be changed with SHOOP_TAX_MODULE setting.

TaxedPrice

A type to represent the return value of tax calculation. Contains a pair of prices, TaxfulPrice and TaxlessPrice, of which one is the original price before the calculation and the other is the calculated price. Also contains a list of the applied taxes. TaxedPrice is the return type of get_taxed_price_for method in the TaxModule interface.

TaxingContext

A container for variables that affect taxing, such as customer tax group, customer tax number, location (country, postal code, etc.). Used in the TaxModule interface. Note: This is not usually subclassed.

Creating Prices

When implementing a PricingModule or another module that has to create prices, use the Shop.create_price method. It makes sure that all prices have the same price unit.

Accessing Prices of Product or Line

There is a Priceful interface for accessing prices. It is implemented by OrderLine and SourceLine, BasketLine, and PriceInfo which is returned e.g. by get_price_info method.