OrcaQubits Saleor Order Management
Before writing code
Fetch live docs:
- Web-search
site:docs.saleor.io orders order lifecycle statusfor order model and state transitions - Web-search
site:docs.saleor.io fulfillments order fulfillmentfor fulfillment creation and tracking - Web-search
site:docs.saleor.io returns refunds orderfor return and refund workflows - Fetch
https://docs.saleor.io/docs/developer/ordersand review order statuses, events, and mutations - Web-search
site:docs.saleor.io draft ordersfor draft order creation and completion patterns - Fetch
https://docs.saleor.io/docs/developer/fulfillmentand review fulfillment line items and tracking
Order Status and States
Order Status
| Status | Description |
|---|---|
UNCONFIRMED |
Order created but not yet confirmed (e.g., pending payment) |
UNFULFILLED |
Order confirmed and paid; no items shipped yet |
PARTIALLY_FULFILLED |
Some items have been shipped |
FULFILLED |
All items have been shipped |
PARTIALLY_RETURNED |
Some items have been returned |
RETURNED |
All items have been returned |
CANCELED |
Order has been cancelled |
Authorization Status
| Status | Description |
|---|---|
NONE |
No payment authorized |
PARTIAL |
Partial amount authorized |
FULL |
Full amount authorized |
Charge Status
| Status | Description |
|---|---|
NONE |
No payment charged |
PARTIAL |
Partial amount charged |
FULL |
Full amount charged |
OVERCHARGED |
Charged amount exceeds order total |
Order Creation Flow
Orders in Saleor are typically created through the checkout completion process:
| Step | Description |
|---|---|
| 1. Checkout completed | Customer completes checkout with payment |
| 2. Order created | System generates order with status UNCONFIRMED or UNFULFILLED |
| 3. Payment confirmed | Transaction events confirm successful charge |
| 4. Ready for fulfillment | Order moves to UNFULFILLED status |
Orders can also be created via draft orders (see below) or programmatically through the
orderCreateFromCheckoutmutation.
Draft Orders
Draft orders allow merchants and staff to create orders manually:
| Operation | Mutation | Notes |
|---|---|---|
| Create draft | draftOrderCreate |
Specify lines, customer, addresses, channel |
| Update draft | draftOrderUpdate |
Modify lines, addresses, discounts |
| Add lines | draftOrderLinesCreate |
Add product variants to draft |
| Delete line | orderLineDelete |
Remove a line from the draft |
| Complete draft | draftOrderComplete |
Convert to a real order |
| Delete draft | draftOrderDelete |
Remove draft before completion |
Fulfillment Flow
Creating a Fulfillment
| Step | Description |
|---|---|
| 1. Query order | Retrieve unfulfilled order lines and warehouse info |
| 2. Create fulfillment | Use orderFulfill with line items and quantities |
| 3. Add tracking | Tracking number and URL included in fulfillment creation |
| 4. Notify customer | Optional email notification on fulfillment |
Key Fulfillment Mutations
| Operation | Mutation | Notes |
|---|---|---|
| Fulfill order | orderFulfill |
Specify lines, quantities, warehouse, tracking |
| Cancel fulfillment | orderFulfillmentCancel |
Restock items optionally |
| Update tracking | orderFulfillmentUpdateTracking |
Update tracking number and URL |
| Approve fulfillment | orderFulfillmentApprove |
For orders requiring approval before shipping |
Fulfillment Status
| Status | Description |
|---|---|
FULFILLED |
Items shipped and tracking assigned |
CANCELED |
Fulfillment cancelled; items may be restocked |
WAITING_FOR_APPROVAL |
Fulfillment created but awaiting staff approval |
REFUNDED |
Fulfillment refunded |
RETURNED |
Items returned from this fulfillment |
REFUNDED_AND_RETURNED |
Items both returned and refunded |
Returns and Refunds
Return Flow
| Step | Description |
|---|---|
| 1. Create return | Use orderFulfillmentReturnProducts with fulfillment lines |
| 2. Specify quantities | Indicate which items and how many are being returned |
| 3. Optional refund | Include refund amount or create refund separately |
| 4. Restock | Optionally restock returned items to warehouse |
Refund Flow
| Operation | Mutation | Notes |
|---|---|---|
| Grant refund | orderGrantRefundCreate |
Create a granted refund (amount or lines) |
| Update grant | orderGrantRefundUpdate |
Modify granted refund before processing |
| Send refund | transactionRequestAction with REFUND |
Process the actual refund via payment App |
Saleor separates the concept of "granting" a refund (merchant decision) from "sending" a refund (payment processing). This allows partial refunds and multi-step refund workflows.
Order Events
Saleor maintains a comprehensive event log for every order:
| Event Type | Description |
|---|---|
PLACED |
Order was placed |
CONFIRMED |
Order was confirmed |
FULFILLMENT_CANCELED |
A fulfillment was cancelled |
FULFILLMENT_FULFILLED_ITEMS |
Items were fulfilled |
PAYMENT_CAPTURED |
Payment was captured |
PAYMENT_REFUNDED |
Payment was refunded |
NOTE_ADDED |
Staff note was added |
EMAIL_SENT |
Notification email was sent |
CANCELED |
Order was cancelled |
Fetch live docs for the complete
OrderEventsEnum-- additional event types exist for tracking, returns, and transaction updates.
Order Line Items
Each order contains OrderLine objects representing purchased items:
| Field | Description |
|---|---|
productName |
Product name at time of purchase |
variantName |
Variant name at time of purchase |
productSku |
SKU at time of purchase |
quantity |
Number of units ordered |
quantityFulfilled |
Number of units already shipped |
unitPrice |
Price per unit (net and gross) |
totalPrice |
Line total (net and gross) |
undiscountedUnitPrice |
Original price before discounts |
Order lines store a snapshot of product data at the time of purchase. Changes to the product after the order do not affect existing orders.
Order Discounts
| Discount Type | Description |
|---|---|
| Voucher | Applied via voucher code during checkout |
| Promotion | Automatic catalog or order promotion |
| Manual discount | Staff-applied discount via orderDiscountAdd |
Key Discount Mutations
| Operation | Mutation |
|---|---|
| Add manual discount | orderDiscountAdd |
| Update discount | orderDiscountUpdate |
| Delete discount | orderDiscountDelete |
Key Admin Queries
| Operation | Query | Notes |
|---|---|---|
| List orders | orders |
Filter by status, date, customer, channel |
| Get order | order |
By ID; includes lines, events, fulfillments |
| Order by token | orderByToken |
Customer-facing order lookup |
Best Practices
- Use draft orders for manual order creation instead of direct order mutations
- Always check
chargeStatusandauthorizeStatusbefore fulfilling - Use
orderFulfillmentReturnProductsfor returns -- it handles restock and refund in one step - Separate grant refund (business decision) from transaction refund (payment action)
- Monitor order events for audit trails and debugging
- Use channel-scoped queries when fetching orders for a specific storefront
- Handle partial fulfillments -- one order may ship from multiple warehouses
- Store additional order metadata using the
metadataandprivateMetadatafields - Always verify stock availability before creating fulfillments
Fetch the Saleor order lifecycle documentation for exact mutation inputs, order event types, and fulfillment patterns before implementing.