# Order lifecycle Source: https://developers.swell.is/guides/core-concepts/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. ### Cart 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. #### Abandoned carts 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. ### Checkout 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. #### Accounts and guest checkout 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`. ### Order creation 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**. > **Note:** Draft orders, as seen from the Swell dashboard, are carts with `draft=true`. Draft orders are carts that have not yet been converted into an actual order. They are designated as carts rather than orders because a cart does not require a customer `account_id`. ### Subscriptions 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. ### Webhooks 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. ### Order status 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"`. **See relevant fields** - `status="pending"`: The default status of an order. - `status="draft"`: The status for an order that has been created but not submitted; draft orders are carts where `draft=true` which will flag the order in the UI. - `status="payment_pending"`: denotes an order that has not yet been paid in full - `status="delivery_pending"`: one or more items in the order are awaiting delivery - `status="complete"`: all items have been received by the customer - `status="hold"`: the order has been put on hold - `status="canceled"`: the order was canceled ### Payments and refunds 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. **See relevant fields** Relevant fields - `authorized_payment_id` - `authorized_payment` - `paid` - `payment_balance` - `payment_marked` - `payment_total` - `payments` - `refund_marked` - `refund_total` - `refunded` #### Payment options 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. ### Fulfillment #### Shipments 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 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. #### Digital delivery 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.](https://developers.swell.is/guides/core-concepts/shipping-and-fulfillment) ### Cancellations 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. ### Returns 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.