Saleor Order Management
Before writing code
Fetch live docs:
- Web-search
site:docs.saleor.io orders order lifecycle status for order model and state transitions
- Web-search
site:docs.saleor.io fulfillments order fulfillment for fulfillment creation and tracking
- Web-search
site:docs.saleor.io returns refunds order for return and refund workflows
- Fetch
https://docs.saleor.io/docs/developer/orders and review order statuses, events, and mutations
- Web-search
site:docs.saleor.io draft orders for draft order creation and completion patterns
- 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.
1---2name: saleor-orders3description: Manage the Saleor order lifecycle — order creation, fulfillments, returns, refunds, draft orders, and order events. Use when working with Saleor orders.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/saleor-orders7---89# Saleor Order Management1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.saleor.io orders order lifecycle status` for order model and state transitions152. Web-search `site:docs.saleor.io fulfillments order fulfillment` for fulfillment creation and tracking163. Web-search `site:docs.saleor.io returns refunds order` for return and refund workflows174. Fetch `https://docs.saleor.io/docs/developer/orders` and review order statuses, events, and mutations185. Web-search `site:docs.saleor.io draft orders` for draft order creation and completion patterns196. Fetch `https://docs.saleor.io/docs/developer/fulfillment` and review fulfillment line items and tracking2021## Order Status and States2223### Order Status2425| Status | Description |26|--------|-------------|27| `UNCONFIRMED` | Order created but not yet confirmed (e.g., pending payment) |28| `UNFULFILLED` | Order confirmed and paid; no items shipped yet |29| `PARTIALLY_FULFILLED` | Some items have been shipped |30| `FULFILLED` | All items have been shipped |31| `PARTIALLY_RETURNED` | Some items have been returned |32| `RETURNED` | All items have been returned |33| `CANCELED` | Order has been cancelled |3435### Authorization Status3637| Status | Description |38|--------|-------------|39| `NONE` | No payment authorized |40| `PARTIAL` | Partial amount authorized |41| `FULL` | Full amount authorized |4243### Charge Status4445| Status | Description |46|--------|-------------|47| `NONE` | No payment charged |48| `PARTIAL` | Partial amount charged |49| `FULL` | Full amount charged |50| `OVERCHARGED` | Charged amount exceeds order total |5152## Order Creation Flow5354Orders in Saleor are typically created through the checkout completion process:5556| Step | Description |57|------|-------------|58| 1. Checkout completed | Customer completes checkout with payment |59| 2. Order created | System generates order with status `UNCONFIRMED` or `UNFULFILLED` |60| 3. Payment confirmed | Transaction events confirm successful charge |61| 4. Ready for fulfillment | Order moves to `UNFULFILLED` status |6263> Orders can also be created via draft orders (see below) or programmatically through the `orderCreateFromCheckout` mutation.6465## Draft Orders6667Draft orders allow merchants and staff to create orders manually:6869| Operation | Mutation | Notes |70|-----------|----------|-------|71| Create draft | `draftOrderCreate` | Specify lines, customer, addresses, channel |72| Update draft | `draftOrderUpdate` | Modify lines, addresses, discounts |73| Add lines | `draftOrderLinesCreate` | Add product variants to draft |74| Delete line | `orderLineDelete` | Remove a line from the draft |75| Complete draft | `draftOrderComplete` | Convert to a real order |76| Delete draft | `draftOrderDelete` | Remove draft before completion |7778## Fulfillment Flow7980### Creating a Fulfillment8182| Step | Description |83|------|-------------|84| 1. Query order | Retrieve unfulfilled order lines and warehouse info |85| 2. Create fulfillment | Use `orderFulfill` with line items and quantities |86| 3. Add tracking | Tracking number and URL included in fulfillment creation |87| 4. Notify customer | Optional email notification on fulfillment |8889### Key Fulfillment Mutations9091| Operation | Mutation | Notes |92|-----------|----------|-------|93| Fulfill order | `orderFulfill` | Specify lines, quantities, warehouse, tracking |94| Cancel fulfillment | `orderFulfillmentCancel` | Restock items optionally |95| Update tracking | `orderFulfillmentUpdateTracking` | Update tracking number and URL |96| Approve fulfillment | `orderFulfillmentApprove` | For orders requiring approval before shipping |9798### Fulfillment Status99100| Status | Description |101|--------|-------------|102| `FULFILLED` | Items shipped and tracking assigned |103| `CANCELED` | Fulfillment cancelled; items may be restocked |104| `WAITING_FOR_APPROVAL` | Fulfillment created but awaiting staff approval |105| `REFUNDED` | Fulfillment refunded |106| `RETURNED` | Items returned from this fulfillment |107| `REFUNDED_AND_RETURNED` | Items both returned and refunded |108109## Returns and Refunds110111### Return Flow112113| Step | Description |114|------|-------------|115| 1. Create return | Use `orderFulfillmentReturnProducts` with fulfillment lines |116| 2. Specify quantities | Indicate which items and how many are being returned |117| 3. Optional refund | Include refund amount or create refund separately |118| 4. Restock | Optionally restock returned items to warehouse |119120### Refund Flow121122| Operation | Mutation | Notes |123|-----------|----------|-------|124| Grant refund | `orderGrantRefundCreate` | Create a granted refund (amount or lines) |125| Update grant | `orderGrantRefundUpdate` | Modify granted refund before processing |126| Send refund | `transactionRequestAction` with `REFUND` | Process the actual refund via payment App |127128> 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.129130## Order Events131132Saleor maintains a comprehensive event log for every order:133134| Event Type | Description |135|------------|-------------|136| `PLACED` | Order was placed |137| `CONFIRMED` | Order was confirmed |138| `FULFILLMENT_CANCELED` | A fulfillment was cancelled |139| `FULFILLMENT_FULFILLED_ITEMS` | Items were fulfilled |140| `PAYMENT_CAPTURED` | Payment was captured |141| `PAYMENT_REFUNDED` | Payment was refunded |142| `NOTE_ADDED` | Staff note was added |143| `EMAIL_SENT` | Notification email was sent |144| `CANCELED` | Order was cancelled |145146> **Fetch live docs** for the complete `OrderEventsEnum` -- additional event types exist for tracking, returns, and transaction updates.147148## Order Line Items149150Each order contains `OrderLine` objects representing purchased items:151152| Field | Description |153|-------|-------------|154| `productName` | Product name at time of purchase |155| `variantName` | Variant name at time of purchase |156| `productSku` | SKU at time of purchase |157| `quantity` | Number of units ordered |158| `quantityFulfilled` | Number of units already shipped |159| `unitPrice` | Price per unit (net and gross) |160| `totalPrice` | Line total (net and gross) |161| `undiscountedUnitPrice` | Original price before discounts |162163> 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.164165## Order Discounts166167| Discount Type | Description |168|---------------|-------------|169| Voucher | Applied via voucher code during checkout |170| Promotion | Automatic catalog or order promotion |171| Manual discount | Staff-applied discount via `orderDiscountAdd` |172173### Key Discount Mutations174175| Operation | Mutation |176|-----------|----------|177| Add manual discount | `orderDiscountAdd` |178| Update discount | `orderDiscountUpdate` |179| Delete discount | `orderDiscountDelete` |180181## Key Admin Queries182183| Operation | Query | Notes |184|-----------|-------|-------|185| List orders | `orders` | Filter by status, date, customer, channel |186| Get order | `order` | By ID; includes lines, events, fulfillments |187| Order by token | `orderByToken` | Customer-facing order lookup |188189## Best Practices190191- Use draft orders for manual order creation instead of direct order mutations192- Always check `chargeStatus` and `authorizeStatus` before fulfilling193- Use `orderFulfillmentReturnProducts` for returns -- it handles restock and refund in one step194- Separate grant refund (business decision) from transaction refund (payment action)195- Monitor order events for audit trails and debugging196- Use channel-scoped queries when fetching orders for a specific storefront197- Handle partial fulfillments -- one order may ship from multiple warehouses198- Store additional order metadata using the `metadata` and `privateMetadata` fields199- Always verify stock availability before creating fulfillments200201Fetch the Saleor order lifecycle documentation for exact mutation inputs, order event types, and fulfillment patterns before implementing.