The order lifecycle

Swell has a complete Order Management System (OMS) with integrated models for carts, orders, payments, refunds, shipments, and returns. Together, these provide a customizable workflow for creating, managing, and fulfilling orders—with the ability to handle returns and abandoned carts out of the box.

Most shopping flows use a cart to keep track of the items the customer wants to buy. The cart contains the shipping and billing information as well. Think of a cart as a staging area for an order. It contains all the information needed to complete a checkout flow.

Swell's abandoned cart feature sends notifications to a customer who has left items in their cart. By default, this action is engaged once a cart has been inactive for at least three hours. For an abandoned cart, the abandoned field will be marked true until the cart sees additional activity.

Enable abandoned cart notifications by navigating to Settings > Notifications > Abandoned cart in the Swell dashboard. Here you can set a variety of parameters such as when a cart is considered abandoned, follow-up notification sequencing, and the contents of those messages.

A checkout flow is a self-serve mechanism for customers to provide delivery and payment details. This process converts their cart into an order that is ready to be fulfilled. When checkout succeeds, all items from the cart are duplicated to an order, and the cart status becomes converted.

Swell provides a hosted checkout which is available on any cart via the checkout_url field. You can also build your own custom checkout flows using our APIs.

Every checkout has an account assigned to it by email, but not every checkout requires a login with password credentials. By default, Swell's hosted checkout allows for guests to make purchases. These customers will be recorded with an email and shipping information only and guest purchases can be identified by guest=true.

Orders can be created from customer carts via a checkout flow, directly via the Backend API, or manually from the dashboard. You can check whether an order originated from a cart using the cart or cart_id fields.

When an order is created, the order number is automatically assigned. The number format is customizable from the dashboard under General > Settings > Order number format.

In the case of one-time purchases, a single order will handle the entire purchase flow. When an order contains subscription products, a subscription entry will be generated to handle recurring billing and fulfillment. Each subscription references the order that generated it as order_id.

For subscriptions with physical products, each interval generates a new order to be fulfilled and charges the customer's saved payment method. These recurring orders can be traced back to the subscription that generated them using the subscription_id or subscription fields.

Subscriptions containing only virtual products do not generate new orders since there are no items to be fulfilled. On each billing interval, an invoice is generated for charging the customer's saved payment method. Like recurring orders, invoices reference the associated subscription with the subscription_id and subscription fields.

Swell features real-time webhooks that allow you to set fields on the order object before being submitted. Use these to update tax and shipping rates or make other determinations such as fraud risk and regulatory approval before processing an order.

The status of an order is provisioned by the system once certain parameters have been met. It is set to "pending" by default. As an order progresses through its lifecycle, the system updates the status accordingly. This is reflected in both the dashboard and via API. An order lifecycle generally includes "pending", "payment_pending", "delivery_pending", and "complete".

Payments and refunds are always related to an order or invoice, and any transaction will automatically update the relevant fields. Orders and invoices will have paid=true when payment_balance is zero or payment_marked=true is manually set. Refunds are issued against a payment and cannot exceed the total payment amount.

During checkout, the payment gateways you have configured will determine how customers can pay for their orders. By default, they can also redeem a gift card or use account credit. Alternative payment methods like cash or bank transfers can be defined in Settings > Payments.

When creating an order from the dashboard, an invoice notification can be sent to the customer with a link to pay for their order. This is the same checkout_url that is present on carts.

At the time of checkout, a user will select a shipment service, which includes both a carrier (e.g., UPS) and a shipping method (e.g., 2-day delivery). This combination of a carrier and shipping method calculates the shipment_total based on the customer's shipping information. Swell calculates shipping rates at the product level based on variables such as the product dimensions(shipment_dimensions), weight(shipment_weight), and quantity per package(shipment_package_quantity).

Shipping rules are defined within Swell Admin under Settings > Shipping. This is where you set your store's store location which is used to calculate shipping rates. Shipping rules created in the Shipping tab can be applied to orders via checkout by the customer. These rules are highly flexible and can be overridden when designated parameters are met. Swell also allows local pick-up options.

Dynamic real-time shipping rate calculations can also be implemented through integrations with shipping carriers and Swell's webhook support. These rates will be calculated during checkout based on the product information within the customer's cart.

Swell can be used to sell virtual products such as services, memberships, and digital goods. Because of the many potential use cases, there isn't a standard delivery mechanism for these; however, you can use queued webhooks and our Backend API to fulfill virtual products in a way that suits your needs.

For more details regarding shipping setup and fulfillment, see our dedicated guide.

Entire orders or specific items within an order can be canceled at any time—even after a customer has received their product. The entire order must be canceled if it contains a single item. When an order is canceled, specify the item and quantity. Optionally, you can include the cancel_reason for the cancellation.

Typically, a return is initiated by a customer. The return is associated with the order_id and the items being returned. Once shipped, a return can optionally be updated with the return's shipping carrier, service, and the tracking_code to keep track of the return shipment's transit to the return address.

Returns can also be facilitated through the dashboard by selecting an order and choosing Actions > Return items—specify the return items and quantity, refund, restocking fee if applicable, and optionally add notes.