Shopify Orders

---
name: shopify-orders
description: Manage Shopify orders — order lifecycle, FulfillmentOrder model, returns and refunds, draft orders, order editing, transactions, metafields, and risk analysis. Use when working with Shopify order processing.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# Shopify Order Management

## Before writing code

**Fetch live docs**:
1. Web-search `site:shopify.dev graphql admin api orders` for order queries and mutations
2. Web-search `site:shopify.dev fulfillment order api` for fulfillment model
3. Web-search `site:shopify.dev returns refunds api` for returns processing
4. Fetch `https://shopify.dev/docs/api/admin-graphql` and search for `fulfillmentCreateV2`, `returnCreate`, `refundCreate` for current input schemas
5. Web-search `site:shopify.dev order editing api` for order modification workflow

## Order Lifecycle

```
Created → Paid → Fulfilled → Completed
  ↓         ↓       ↓
Cancelled  Refunded  Returned
```

### Order Statuses

| Status | Meaning |
|--------|---------|
| `OPEN` | Order placed, payment authorized or pending |
| `CLOSED` | All items fulfilled and no further action needed |
| `CANCELLED` | Order cancelled by merchant or customer |

### Financial Status

| Status | Meaning |
|--------|---------|
| `PENDING` | Payment not yet processed |
| `AUTHORIZED` | Payment authorized but not captured |
| `PAID` | Payment captured successfully |
| `PARTIALLY_PAID` | Partial payment received |
| `PARTIALLY_REFUNDED` | Some items refunded |
| `REFUNDED` | Fully refunded |
| `VOIDED` | Authorization voided |

### Fulfillment Status

| Status | Meaning |
|--------|---------|
| `UNFULFILLED` | No items shipped |
| `PARTIALLY_FULFILLED` | Some items shipped |
| `FULFILLED` | All items shipped |
| `RESTOCKED` | Items returned and restocked |

## Querying Orders

```graphql
# Pattern: paginated order query with filter
# Fetch live docs for current queryable fields
query Orders($first: Int!, $query: String) {
  orders(first: $first, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        displayFulfillmentStatus
        totalPriceSet { shopMoney { amount currencyCode } }
        customer { id firstName lastName email }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}
```

Filter examples: `"financial_status:paid fulfillment_status:unfulfilled"`, `"created_at:>2025-01-01"`, `"tag:rush"`.

> **Fetch live docs** for the full query filter syntax and available `displayFinancialStatus`/`displayFulfillmentStatus` enum values.

## FulfillmentOrder Model

The modern fulfillment API (replaces legacy Fulfillment):
- Each order has one or more `FulfillmentOrder` objects
- Each FulfillmentOrder is assigned to a fulfillment location
- Supports third-party fulfillment services
- Lifecycle: `OPEN` → `IN_PROGRESS` → `CLOSED`

### Key Fulfillment Mutations

| Operation | Mutation |
|-----------|----------|
| Create fulfillment | `fulfillmentCreateV2` |
| Cancel fulfillment | `fulfillmentCancel` |
| Update tracking | `fulfillmentTrackingInfoUpdateV2` |
| Move to new location | `fulfillmentOrderMove` |
| Hold fulfillment | `fulfillmentOrderHold` |
| Release hold | `fulfillmentOrderReleaseHold` |

Fulfillment creation requires: fulfillment order ID, line items with quantities, tracking info (number, URL, company), and notify customer flag.

> **Fetch live docs** for `FulfillmentV2Input` fields and `fulfillmentOrderLineItems` shape — these are the most commonly misused inputs.

## Returns and Refunds

### Returns

```
Return Requested → Return Approved → Items Received → Refund Issued
```

Key mutations:
- `returnCreate` — initiate a return (requires order ID, line items, quantities, return reason)
- `returnApproveRequest` — approve customer return request
- `returnRefund` — issue refund for returned items

Return reasons: `DEFECTIVE`, `WRONG_ITEM`, `SIZE_TOO_SMALL`, `SIZE_TOO_LARGE`, `STYLE`, `COLOR`, `DAMAGED_IN_TRANSIT`, `OTHER`, `UNKNOWN`.

> **Fetch live docs** for `ReturnInput` fields and the current list of return reason enum values.

### Refunds

Key mutation: `refundCreate` (requires order ID, line items, quantities, restock type, optional shipping refund).

Restock types: `RETURN` (back to location), `CANCEL` (restock), `NO_RESTOCK` (don't adjust inventory).

> **Fetch live docs** for `RefundInput` fields — refund shipping, note, and currency options vary by API version.

## Draft Orders

Orders created manually by merchants or apps:
- `draftOrderCreate` — create draft with custom pricing
- `draftOrderComplete` — convert to real order (charges payment)
- Use for: custom orders, B2B quotes, phone orders, wholesale pricing
- Can apply custom discounts and shipping rates

> **Fetch live docs** for `DraftOrderInput` fields — custom line items, applied discounts, and shipping lines shape.

## Order Editing

Modify orders after creation (three-step workflow):

1. `orderEditBegin` — start editing session (returns calculated order ID)
2. Make changes: `orderEditAddVariant`, `orderEditSetQuantity`, `orderEditAddDiscount`, `orderEditRemoveLineItemDiscount`
3. `orderEditCommit` — apply changes (adjusts payment if needed)

> **Fetch live docs**: Web-search `site:shopify.dev order editing api` for exact mutation sequence and calculated order fields.

## Order Metafields

Store custom data on orders via `metafieldsSet` (same pattern as product metafields — specify `ownerId` as the order GID).

## Transactions

Payment records on orders:
- Types: authorization, capture, void, refund
- Multiple transactions per order (e.g., authorize then capture)
- Gateway-specific transaction data accessible via `order.transactions`

## Webhook Topics

| Topic | When Fired |
|-------|-----------|
| `orders/create` | New order placed |
| `orders/updated` | Order modified |
| `orders/paid` | Payment captured |
| `orders/fulfilled` | All items shipped |
| `orders/cancelled` | Order cancelled |

> **Fetch live docs** for the complete list of order-related webhook topics and payload shapes.

## Best Practices

- Use FulfillmentOrder model (not legacy Fulfillment) — it's the current standard
- Always check financial status before fulfilling
- Use order editing API instead of cancelling and recreating
- Implement idempotent order processing (check for existing orders before creating)
- Use webhooks (`orders/create`, `orders/paid`, `orders/fulfilled`) for real-time notifications
- Store custom order data in metafields
- Use `query` parameter for filtering orders server-side (not client-side filtering)
- Handle partial fulfillments — one order can span multiple locations

Fetch the Shopify order and fulfillment API documentation for exact mutation inputs, order lifecycle states, and fulfillment patterns before implementing.