Magento Orders

Magento Order Operations (REST)

This skill calls Magento's admin REST API directly — no MCP server needed.

Configuration

echo "MAGENTO_BASE_URL=${MAGENTO_BASE_URL:-NOT SET}"
echo "MAGENTO_ADMIN_TOKEN=${MAGENTO_ADMIN_TOKEN:+SET (${#MAGENTO_ADMIN_TOKEN} chars)}"
echo "MAGENTO_STORE_CODE=${MAGENTO_STORE_CODE:-default}"

• Base URL: ${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/
• Auth: Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}

If either env var is missing, stop and ask the user to set them.

---

Operation 1: Search Orders

Use when the user asks for "recent orders", "orders by customer", "pending orders", or any order list.

Endpoint

GET /rest/default/V1/orders?searchCriteria[...]

searchCriteria Pattern

searchCriteria[filterGroups][0][filters][0][field]=
searchCriteria[filterGroups][0][filters][0][value]=
searchCriteria[filterGroups][0][filters][0][conditionType]=
searchCriteria[pageSize]=
searchCriteria[currentPage]=1
searchCriteria[sortOrders][0][field]=created_at
searchCriteria[sortOrders][0][direction]=DESC

Condition types: eq, neq, gt, gteq, lt, lteq, like, in, notnull, null, from, to.

Common Filters

| What | Field | Condition | Value | |------|-------|-----------|-------| | By status | status | eq | pending, processing, complete, canceled, holded | | By customer email | customer_email | eq | customer@example.com | | By customer ID | customer_id | eq | 5 | | By increment ID | increment_id | eq | 000000001 | | Orders since date | created_at | gteq | 2024-01-01 00:00:00 | | Orders in range | created_at | from/to | 2024-01-01 00:00:00 | | Grand total | grand_total | gteq | 100 |

Practical Examples

Recent 10 orders:

curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders?searchCriteria[pageSize]=10&searchCriteria[sortOrders][0][field]=created_at&searchCriteria[sortOrders][0][direction]=DESC" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

Orders by status:

curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=status&searchCriteria[filterGroups][0][filters][0][value]=processing&searchCriteria[filterGroups][0][filters][0][conditionType]=eq&searchCriteria[pageSize]=20&searchCriteria[sortOrders][0][field]=created_at&searchCriteria[sortOrders][0][direction]=DESC" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

Orders by customer email:

curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=customer_email&searchCriteria[filterGroups][0][filters][0][value]=roni_cost@example.com&searchCriteria[filterGroups][0][filters][0][conditionType]=eq&searchCriteria[pageSize]=10&searchCriteria[sortOrders][0][field]=created_at&searchCriteria[sortOrders][0][direction]=DESC" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

Response Fields to Extract

From the items array, surface:

• increment_id — customer-facing order number
• entity_id — internal ID (needed for write operations)
• status — current status
• created_at — order date
• customer_firstname, customer_lastname, customer_email
• grand_total, base_currency_code
• total_item_count

---

Operation 2: Get Order Detail

Use when the user asks about a specific order (items, addresses, tracking, comments).

By entity_id (internal ID)

curl -s "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders/${ENTITY_ID}" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

By increment_id (customer order number)

Search first to get entity_id, then fetch by ID:

curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=increment_id&searchCriteria[filterGroups][0][filters][0][value]=000000001&searchCriteria[filterGroups][0][filters][0][conditionType]=eq" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

Key Response Fields

• items[] — line items: sku, name, qty_ordered, qty_shipped, qty_invoiced, price, row_total
• billing_address, extension_attributes.shipping_assignments[0].address — addresses
• status_histories[] — order comment/status history (sorted by created_at)
• payment.method — payment method code
• extension_attributes.shipping_assignments[0].shipping.total — shipping info
• extension_attributes.payment_additional_info[] — transaction reference

PII note: REST order responses contain full customer/address/payment data. Never display raw payment info. Mask email, show street as "[REDACTED]" if showing to support agents.

---

Operation 3: Get Tracking Numbers

Use when the user asks for shipping tracking, "where is my order", "has this shipped".

curl -s "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/shipments?searchCriteria[filterGroups][0][filters][0][field]=order_id&searchCriteria[filterGroups][0][filters][0][value]=${ENTITY_ID}&searchCriteria[filterGroups][0][filters][0][conditionType]=eq" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

From response: items[].tracks[] contains track_number, title (carrier name), carrier_code.

---

Operation 4: Add Order Comment (Write — Confirm First)

Always confirm with user before executing. Tell the user what will be done and ask: "Shall I add this comment to order #XXXXXX?"

curl -s -X POST "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders/${ENTITY_ID}/comments" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"statusHistory": {"comment": "Customer called, confirmed delivery address.", "is_customer_notified": 0, "is_visible_on_front": 0, "status": "processing"}}'

---

Operation 5: Cancel Order (Write — Confirm First)

Always confirm with user before executing. This cannot be undone if the order has been invoiced.

curl -s -X POST "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders/${ENTITY_ID}/cancel" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

Response is true on success.

---

Operation 6: Hold / Unhold Order (Write — Confirm First)

Hold:

curl -s -X POST "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders/${ENTITY_ID}/hold" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

Unhold:

curl -s -X POST "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders/${ENTITY_ID}/unhold" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

---

Response Formatting

Order list:

• Numbered list: #000000001 | processing | Jane Doe | $125.00 | 2024-01-15
• Total: "Showing X of Y orders"
• Offer to filter by status, date, or customer

Order detail:

• Header: order number, status, date, customer name (masked email)
• Line items table: name, qty ordered/shipped/refunded, unit price, row total
• Shipping address (city + state only unless explicitly asked for full address)
• Status history: last 3 entries with date and comment
• Tracking numbers if shipped

Write confirmations: Before any POST: "I'll [action] on order #XXXXXX. Confirm? (yes/no)"

---

Error Handling

• HTTP 401: Token missing or expired. Check MAGENTO_ADMIN_TOKEN.
• HTTP 404: Order not found. Confirm the entityid or incrementid.
• HTTP 400: Bad request — check field names and condition types in searchCriteria.
• message: "You cannot cancel this order" etc.: Show Magento's error message directly to the user.

---

Decision Table

| User says | Action | |-----------|--------| | "recent orders" / "last orders" | Search, sorted by createdat DESC, pageSize=10 | | "orders for [email]" | Search by customeremail eq | | "order #000000001" | Search by increment_id, then get detail | | "pending orders" | Search by status=pending | | "where is order 123" | Get detail + get shipments/tracking | | "cancel order 123" | Confirm, then POST /cancel | | "put order 123 on hold" | Confirm, then POST /hold | | "add a note to order 123" | Confirm comment text, then POST /comments |

---

Operation 7: Order Analytics (Revenue / AOV / Count)

Magento has no native aggregate stats endpoint. Fetch all orders in the date range and aggregate with jq or python3.

Important: If total_count > pageSize, you must paginate to get all orders. Use pageSize=100 and loop pages.

# Fetch all orders in a date range (single page — adjust if total_count > 100)
export FROM_DATE="2026-01-01 00:00:00"
export TO_DATE="2026-03-31 23:59:59"

curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=created_at&searchCriteria[filterGroups][0][filters][0][value]=${FROM_DATE}&searchCriteria[filterGroups][0][filters][0][conditionType]=gteq&searchCriteria[filterGroups][1][filters][0][field]=created_at&searchCriteria[filterGroups][1][filters][0][value]=${TO_DATE}&searchCriteria[filterGroups][1][filters][0][conditionType]=lteq&searchCriteria[filterGroups][2][filters][0][field]=status&searchCriteria[filterGroups][2][filters][0][value]=canceled&searchCriteria[filterGroups][2][filters][0][conditionType]=neq&searchCriteria[pageSize]=100&searchCriteria[currentPage]=1" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" | \
  jq '{
    total_orders: .total_count,
    revenue: ([.items[].grand_total] | add // 0),
    aov: (([.items[].grand_total] | add // 0) / ((.items | length) | if . == 0 then 1 else . end)),
    note: (if .total_count > (.items | length) then "WARNING: results truncated — paginate for full data" else "complete" end)
  }'

Paginating for large result sets:

export FROM_DATE="2026-01-01 00:00:00"
export TO_DATE="2026-03-31 23:59:59"
PAGE=1; TOTAL=0; REVENUE=0; COUNT=0

while true; do
  RESULT=$(curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=created_at&searchCriteria[filterGroups][0][filters][0][value]=${FROM_DATE}&searchCriteria[filterGroups][0][filters][0][conditionType]=gteq&searchCriteria[filterGroups][1][filters][0][field]=created_at&searchCriteria[filterGroups][1][filters][0][value]=${TO_DATE}&searchCriteria[filterGroups][1][filters][0][conditionType]=lteq&searchCriteria[filterGroups][2][filters][0][field]=status&searchCriteria[filterGroups][2][filters][0][value]=canceled&searchCriteria[filterGroups][2][filters][0][conditionType]=neq&searchCriteria[pageSize]=100&searchCriteria[currentPage]=${PAGE}" \
    -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}")
  TOTAL=$(echo "$RESULT" | jq '.total_count')
  PAGE_REV=$(echo "$RESULT" | jq '[.items[].grand_total] | add // 0')
  PAGE_COUNT=$(echo "$RESULT" | jq '.items | length')
  REVENUE=$(python3 -c "print($REVENUE + $PAGE_REV)")
  COUNT=$((COUNT + PAGE_COUNT))
  [ $COUNT -ge $TOTAL ] && break
  PAGE=$((PAGE + 1))
done

python3 -c "
revenue=$REVENUE; count=$COUNT
print(f'Orders: {count}')
print(f'Revenue: €{revenue:,.2f}')
print(f'AOV: €{revenue/count:,.2f}' if count > 0 else 'AOV: n/a')
"

Break down by status:

curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=created_at&searchCriteria[filterGroups][0][filters][0][value]=2026-01-01 00:00:00&searchCriteria[filterGroups][0][filters][0][conditionType]=gteq&searchCriteria[pageSize]=100" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" | \
  jq '.items | group_by(.status) | map({status: .[0].status, count: length, revenue: ([.[].grand_total] | add)}) | sort_by(.count) | reverse'

---

Operation 8: Abandoned Cart / Quote Search

Magento stores active and abandoned carts as quotes. Status 1=open (active/abandoned).

# Recent abandoned carts (open quotes updated > 1 day ago)
curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/carts?searchCriteria[filterGroups][0][filters][0][field]=is_active&searchCriteria[filterGroups][0][filters][0][value]=1&searchCriteria[filterGroups][0][filters][0][conditionType]=eq&searchCriteria[filterGroups][1][filters][0][field]=items_count&searchCriteria[filterGroups][1][filters][0][value]=0&searchCriteria[filterGroups][1][filters][0][conditionType]=gt&searchCriteria[pageSize]=20&searchCriteria[sortOrders][0][field]=updated_at&searchCriteria[sortOrders][0][direction]=DESC" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

Extract: entity_id, customer_email, customer_firstname, customer_lastname, grand_total, items_count, created_at, updated_at, items[].name, items[].sku, items[].qty

PII note: Mask customer_email in output (r***@e***.com). Show customer name as initials only (e.g., V. C.). Never display raw email addresses in abandoned cart reports.

Filter by cart value (high-value abandoned carts):

# Carts with > €100 grand_total
curl -s -g "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/carts?searchCriteria[filterGroups][0][filters][0][field]=is_active&searchCriteria[filterGroups][0][filters][0][value]=1&searchCriteria[filterGroups][0][filters][0][conditionType]=eq&searchCriteria[filterGroups][1][filters][0][field]=grand_total&searchCriteria[filterGroups][1][filters][0][value]=100&searchCriteria[filterGroups][1][filters][0][conditionType]=gteq&searchCriteria[pageSize]=20&searchCriteria[sortOrders][0][field]=grand_total&searchCriteria[sortOrders][0][direction]=DESC" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json"

Guest carts: Guest carts have customer_is_guest: true and no customer_id. They still show email if the customer entered it during checkout.

---

Response Formatting (additions)

Analytics:

Order Analytics: 2026-01-01 → 2026-03-31
Orders: 142 (excluding canceled)
Revenue: €18,450.00
AOV: €129.93

By status:
  complete:    98 orders | €14,200.00
  processing:  32 orders | €3,800.00
  holded:       8 orders | €450.00
  pending:      4 orders | €0.00

Abandoned carts:

Top 5 abandoned carts (by value):
1. V. C. (r***@e***.com) | €285.00 | 3 items | last active 2 days ago
2. J. D. (j***@e***.com) | €199.99 | 1 item  | last active 5 days ago

---

Decision Table (updated)

| User says | Action | |-----------|--------| | "recent orders" / "last orders" | Op 1 — Search, sorted by createdat DESC | | "orders for [email]" | Op 1 — Search by customeremail | | "order #000000001" | Op 1 search by incrementid → Op 2 detail | | "pending orders" | Op 1 — Search by status=pending | | "where is order 123" | Op 2 detail + Op 3 tracking | | "cancel order 123" | Confirm → Op 5 | | "put order 123 on hold" | Confirm → Op 6 | | "add a note to order 123" | Confirm → Op 4 | | "revenue this month / analytics" | Op 7 with date range | | "abandoned carts" | Op 8 | | "high-value abandoned carts" | Op 8 with grandtotal filter |

User Request

$ARGUMENTS

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: magendooro
• Source: magendooro/magento-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.