Orders

Orders reference.

Models

class salesman.orders.models.ParentalForeignKey(*args, **kwargs)[source]

Use this foreign key to add support for Wagtail in case modelcluster is installed.

class salesman.orders.models.BaseOrder(*args: Any, **kwargs: Any)[source]
save(*args: Any, **kwargs: Any) None[source]

Save the model and commit all child relations.

pay(amount: Decimal, transaction_id: str, payment_method: str = '') BaseOrderPayment[source]

Create a new payment for order.

Parameters:
  • amount (Decimal) – Amount to add

  • transaction_id (str) – ID of transaction

  • payment_method (str, optional) – Payment method identifier. Defaults to ‘’.

Returns:

New order payment instance

Return type:

OrderPayment

populate_from_basket(basket: BaseBasket, request: HttpRequest, **kwargs: Any) None[source]

Populate order with items from basket.

Parameters:
  • basket (Basket) – Basket instance

  • request (HttpRequest) – Django request

get_items() list[salesman.orders.models.BaseOrderItem][source]

Returns items from cache or stores new ones.

Status

alias of OrderStatus

property status_display: str

Returns display label for current status.

amount_paid

Returns amount already paid for this order.

property amount_outstanding: Decimal

Returns amount still needed for order to be paid.

property is_paid: bool

Returns if order is paid in full.

classmethod get_wagtail_admin_attribute(name: str) Any | None[source]

Return attribute from Wagtail order admin mixin.

Parameters:

name (str) – Attribute name

Returns:

Attribute value

Return type:

Optional[Any]

class salesman.orders.models.Order(*args: Any, **kwargs: Any)[source]

Model that can be swapped by overriding SALESMAN_ORDER_MODEL setting.

exception DoesNotExist
exception MultipleObjectsReturned
class salesman.orders.models.BaseOrderItem(*args: Any, **kwargs: Any)[source]
save(*args: Any, **kwargs: Any) None[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.

populate_from_basket_item(item: BaseBasketItem, request: HttpRequest) None[source]

Populate order with items from basket.

Parameters:
  • item (BasketItem) – Basket item instance

  • request (HttpRequest) – Django request

property name: str

Returns product name from stored data.

property code: str

Returns product name from stored data.

class salesman.orders.models.OrderItem(*args: Any, **kwargs: Any)[source]

Model that can be swapped by overriding SALESMAN_ORDER_ITEM_MODEL setting.

exception DoesNotExist
exception MultipleObjectsReturned
class salesman.orders.models.BaseOrderPayment(*args, **kwargs)[source]
get_payment_method() PaymentMethod | None[source]

Returns payment method instance.

property payment_method_display: str

Returns display label for payment method.

class salesman.orders.models.OrderPayment(*args, **kwargs)[source]

Model that can be swapped by overriding SALESMAN_ORDER_PAYMENT_MODEL setting.

exception DoesNotExist
exception MultipleObjectsReturned
class salesman.orders.models.BaseOrderNote(*args, **kwargs)[source]
class salesman.orders.models.OrderNote(*args, **kwargs)[source]

Model that can be swapped by overriding SALESMAN_ORDER_NOTE_MODEL setting.

exception DoesNotExist
exception MultipleObjectsReturned

Serializers

class salesman.orders.serializers.OrderItemSerializer(*args, **kwargs)[source]

Serializer for order item.

class salesman.orders.serializers.OrderPaymentSerializer(*args, **kwargs)[source]

Serializer for order payment.

class salesman.orders.serializers.OrderNoteSerializer(*args, **kwargs)[source]

Serializer for order note.

class salesman.orders.serializers.OrderSerializer(*args, **kwargs)[source]

Serializer for order.

class salesman.orders.serializers.StatusTransitionSerializer(*args, **kwargs)[source]

Serializer to display order status with error.

to_representation(status: str) Any[source]

Object instance -> Dict of primitive datatypes.

class salesman.orders.serializers.OrderStatusSerializer(*args, **kwargs)[source]

Serializer used to change order status.

to_representation(instance: BaseOrder) Any[source]

Object instance -> Dict of primitive datatypes.

class salesman.orders.serializers.OrderPaySerializer(*args, **kwargs)[source]

Serializer used to pay for existing order via payment method.

class salesman.orders.serializers.OrderRefundSerializer(*args, **kwargs)[source]

Serializer used to issue an order refund.

Signals

Status

class salesman.orders.status.BaseOrderStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Base order status enum, actuall choices must extend this class.

classmethod get_payable() list[str][source]

Returns list of statuses from which an order is eligible for payment.

classmethod get_transitions() dict[str, list[str]][source]

Returns a dict of statuses with their transitions. If not specified for status, any transition is valid.

classmethod validate_transition(status: str, order: BaseOrder) str[source]

Validate a given status transition for the order. By default check status is defined in transitions.

Parameters:
  • status (str) – New status

  • order (Order) – Order instance

Raises:

ValidationError – If transition not valid

Returns:

Validated status

Return type:

str

class salesman.orders.status.OrderStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Default order choices enum. Can be overriden by providing a dotted path to a class in SALESMAN_ORDER_STATUS setting. Required choices are NEW, CREATED, COMPLETED and REFUNDED.

Utils

salesman.orders.utils.generate_ref(request: HttpRequest) str[source]

Default order reference generator function. Can be overriden by providing a dotted path to a function in SALESMAN_ORDER_REFERENCE_GENERATOR setting.

Default format is {year}-{5-digit-increment} (eg. 2020-00001).

Parameters:

request (HttpRequest) – Django request

Returns:

New order reference

Return type:

str

Views

class salesman.orders.views.OrderViewSet(**kwargs)[source]

Orders API endpoint.

serializer_class

alias of OrderSerializer

get_queryset() QuerySet[source]

Get the list of items for this view. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.

You may want to override this if you need to provide different querysets depending on the incoming request.

(Eg. return a list of items that is specific to the user)

optimize_queryset(queryset: QuerySet) QuerySet[source]

Extract fields for pre-fetching from order serializer and apply to queryset.

get_object() BaseOrder[source]

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

get_serializer_class() type[rest_framework.serializers.BaseSerializer][source]

Return the class to use for the serializer. Defaults to using self.serializer_class.

You may want to override this if you need to provide different serializations depending on the incoming request.

(Eg. admins get full serialization, others get basic serialization)

get_serializer_context() dict[str, Any][source]

Extra context provided to the serializer class.

dispatch(request: HttpRequest, *args: Any, **kwargs: Any) HttpResponseBase[source]

.dispatch() is pretty much the same as Django’s regular dispatch, but with extra hooks for startup, finalize, and exception handling.

last(request: Request) Response[source]

Show last customer order.

all(request: Request) Response[source]

Show all orders to the admin user.

status(request: Request, ref: str) Response[source]

View order status. Available only to admin user.

status_update(request: Request, ref: str) Response[source]

Update order status. Available only to admin user.

pay(request: Request, ref: str) Response[source]

View order payment methods.

pay_create(request: Request, ref: str) Response[source]

Create order payment.

refund(request: Request, ref: str) Response[source]

Refund all order payments.