orcaqubits/saleor-orders

Saleor Order Management

Before writing code

Fetch live docs:

1. Web-search site:docs.saleor.io orders order lifecycle status for order model and state transitions
2. Web-search site:docs.saleor.io fulfillments order fulfillment for fulfillment creation and tracking
3. Web-search site:docs.saleor.io returns refunds order for return and refund workflows
4. Fetch https://docs.saleor.io/docs/developer/orders and review order statuses, events, and mutations
5. Web-search site:docs.saleor.io draft orders for draft order creation and completion patterns
6. Fetch https://docs.saleor.io/docs/developer/fulfillment and 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 orderCreateFromCheckout mutation.

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 chargeStatus and authorizeStatus before fulfilling
• Use orderFulfillmentReturnProducts for 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 metadata and privateMetadata fields
• 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.