Orders

Overview

The order model is a key entity which tracks purchases made by customers on AviaCommerce and possible returns. It gives the admin a way to manage received orders.

The order model has following attributes:

• number: It uniquely identifies the order. At present, it is being generated using nanoid. The order number is available to both the user and the admin and can be used to address any grievances. To get the order details Snitch.Model.Order.get/1 can be used with the order_number as params.
• state: It helps in identifying the current state of the order. An order can be in different states depending on the user interaction throughout the checkout process. To know more about different states of the order, see section Order States.
• special instructions: It is mainly for admin to add any special action to be performed or add some note to the order.
• inserted_at: It identifies the timestamp at which order was created for the first time.
• updated_at: It gives the timestamp when the order was updated with any new information.
• billing_address: It relates to the information regarding the address which is connected with the specific form of payment for this order. See the Address section to know more.
• shipping_address: This field depicts the address to which the order should be shipped. Scroll to Address section to know more.

It has the following relationships:

• has many payments: An order can be paid through one or more payment methods. The order model has been designed in such a manner so as to support partial payments through multiple methods. This is usually required when the stores have a wallet which can be used for making payments and any balance amount after using the store credits can be made through other payment methods.
• has many packages: An order can have multiple packages created under a set of rules. To know more about the rules and package entity, see the Packages section.
• has many line_items: An order can have one or more lineitems depending on the purchases made by the user. See line item section for more info.

Modules responsible for handling the business logic for order model.

• Snitch.Data.Schema.Order: Defines the order schema.
• Snitch.Data.Model.Order: Handles the CRUD functions for order model.
• Snitch.Domain.Order: Exposes Calculation and other important functions.
• Snitch.Domain.Order.Transitions: Exposes Transition function for order state transitions.
• Snitch.Domain.Order.DefaultMachine: The default order state machine to handle state transitions. The default order state machine can be replaced with any custom state machine to handle transitions.

LineItems

A line item is used to keep track of items in the order. It is a kind of a link between the order and products with additional information in terms of purchase made.
When a product is added to an order it’s price is set as the unit price of the line item. This is done so that in case the price of the product changes in future, the line item would reflect the price used at the time of ordering.

Line Item model attributes.

• quantity: It’s about the number of items of a particular type.
• unit_price: The price of an item for that particular product.

Line Item relationships:

• belongs to product: Foreign key association to link the product.
• belongs to order: Foreign key association with the order.

The line item model uses quantity field to maintain item consolidation so that, a new item added to an already existing line item should not be added as a new line item and only the quantity should be updated.

Order States

The order during the checkout flow goes through a series of states. It begins with the order in the cart state and ends at the completed state. The different states of the order are:

• cart
• address
• delivery
• payment
• confirmed
• completed

To move from one state to another the order has to meet certain conditions. To know about the conditions see the order state machine Order States[advanced].

The order can be moved from one state to another using the exposed API call. A successful transition puts the order in the next state, whereas an unsuccessful one keeps the order in the same state and returns an error message. To See the APIs for the transitions see, Checkout API Flow.

Address

An order has two different addresses associated with it:

• Shipping Address
• Billing Address

Both these addresses have their own significance.

Billing Address

The billing address of an order is connected with the payment method used for making the purchase. It is used to identify an authorized use of the card. It is also used as an address to which the bill for the purchase would be sent.
The AVS(Address Verification System) employed by online merchants to identify any fraud related to the payment made is also based on the billing address used.

Shipping Address

It refers to the address to which packages of the order would be sent to. The shipping cost for the order is calculated based on the zone the shipping address falls into.
Some merchants have multiple stock locations for their store. In that case, a package in an order can be fulfilled from multiple stock locations. The stock location from which the package would be shipped is selected based on the shipping address.

Packages

An order in the delivery state consists of multiple packages. These are the actual shippable entities of an order.

Once the order transitions to the confirmed state, further actions happen on packages of the order. The packages also go through a series of state changes based on the admin action. The main states of a package are:

• pending
• ready
• shipped
• delivered
  To know more about packages see, Shipments

Payments

An order can be paid for once it is in the payment state. In the payment state the total for the order has been calculated which includes:

• item total
• shipping cost
• shipping taxes
• item taxes In short all the costs associated with order are calculated and the order can be paid for.

The business logic has been kept in a manner that an order can be paid via multiple payment methods. However, the functionality has not been added at this moment but, it will be added very soon. To know more about the payments functionality see Payments.