Help us improve
Share bugs, ideas, or general feedback.
From shopify-commerce
Guides Shopify order management via GraphQL: lifecycle, FulfillmentOrder, returns/refunds, draft orders, editing, transactions, metafields, risk analysis.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin shopify-commerceHow this skill is triggered — by the user, by Claude, or both
Slash command
/shopify-commerce:shopify-ordersThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Fetch live docs**:
Manages Shopify orders, customers, and fulfillments via GraphQL Admin API. Query orders, process fulfillments, handle customer records, create draft orders.
Manages Saleor order lifecycle: creation (drafts/checkout), fulfillments, returns, refunds, events, statuses. Fetches docs for GraphQL mutations.
Manages Medusa v2 orders: lifecycle and state machine, fulfillment workflows, returns, exchanges, claims, draft orders, and editing. Use for order processing tasks.
Share bugs, ideas, or general feedback.
Fetch live docs:
site:shopify.dev graphql admin api orders for order queries and mutationssite:shopify.dev fulfillment order api for fulfillment modelsite:shopify.dev returns refunds api for returns processinghttps://shopify.dev/docs/api/admin-graphql and search for fulfillmentCreateV2, returnCreate, refundCreate for current input schemassite:shopify.dev order editing api for order modification workflowCreated → Paid → Fulfilled → Completed
↓ ↓ ↓
Cancelled Refunded Returned
| 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 |
| 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 |
| Status | Meaning |
|---|---|
UNFULFILLED | No items shipped |
PARTIALLY_FULFILLED | Some items shipped |
FULFILLED | All items shipped |
RESTOCKED | Items returned and restocked |
# 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/displayFulfillmentStatusenum values.
The modern fulfillment API (replaces legacy Fulfillment):
FulfillmentOrder objectsOPEN → IN_PROGRESS → CLOSED| 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
FulfillmentV2Inputfields andfulfillmentOrderLineItemsshape — these are the most commonly misused inputs.
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 requestreturnRefund — issue refund for returned itemsReturn reasons: DEFECTIVE, WRONG_ITEM, SIZE_TOO_SMALL, SIZE_TOO_LARGE, STYLE, COLOR, DAMAGED_IN_TRANSIT, OTHER, UNKNOWN.
Fetch live docs for
ReturnInputfields and the current list of return reason enum values.
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
RefundInputfields — refund shipping, note, and currency options vary by API version.
Orders created manually by merchants or apps:
draftOrderCreate — create draft with custom pricingdraftOrderComplete — convert to real order (charges payment)Fetch live docs for
DraftOrderInputfields — custom line items, applied discounts, and shipping lines shape.
Modify orders after creation (three-step workflow):
orderEditBegin — start editing session (returns calculated order ID)orderEditAddVariant, orderEditSetQuantity, orderEditAddDiscount, orderEditRemoveLineItemDiscountorderEditCommit — apply changes (adjusts payment if needed)Fetch live docs: Web-search
site:shopify.dev order editing apifor exact mutation sequence and calculated order fields.
Store custom data on orders via metafieldsSet (same pattern as product metafields — specify ownerId as the order GID).
Payment records on orders:
order.transactions| 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.
orders/create, orders/paid, orders/fulfilled) for real-time notificationsquery parameter for filtering orders server-side (not client-side filtering)Fetch the Shopify order and fulfillment API documentation for exact mutation inputs, order lifecycle states, and fulfillment patterns before implementing.