Magento Fulfillment

Magento Fulfillment Documents (REST)

Covers the post-placement order lifecycle: invoices → shipments → credit memos → returns.

Configuration

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

---

Operation 1: Search Invoices

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

Common filters:

| What | Field | Condition | |------|-------|-----------| | By order entity_id | order_id | eq | | By invoice state | state | eq (1=pending, 2=paid, 3=canceled) | | Date range | created_at | from/to |

Extract: increment_id, order_id, state, grand_total, created_at, items[].sku, items[].name, items[].qty

---

Operation 2: Get Invoice by ID

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

---

Operation 3: Create Invoice (Write — Confirm First)

Confirm: "I'll create an invoice for order #XXXXXX. This will capture payment. Confirm? (yes/no)"

Creates an invoice for the entire order (all items, all qty):

curl -s -X POST "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/order/${ORDER_ENTITY_ID}/invoice" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"capture": false, "notify": false}'

• capture: true — attempt online payment capture (requires online payment method)
• capture: false — offline invoice only
• notify: true — send invoice email to customer

To invoice only specific items, include items array:

-d '{"capture": false, "notify": false, "items": [{"order_item_id": 5, "qty": 1}]}'

Response is the new invoice ID (integer) on success.

---

Operation 4: Search Shipments

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

Extract: increment_id, order_id, created_at, items[].sku, items[].qty, tracks[].track_number, tracks[].title (carrier), tracks[].carrier_code

---

Operation 5: Get Shipment by ID

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

---

Operation 6: Create Shipment (Write — Confirm First)

IMPORTANT: Always use POST /V1/order/{orderId}/ship, NOT POST /V1/shipment. The /V1/shipment endpoint can create duplicate shipments if called multiple times; the order-scoped endpoint validates against order state.

Confirm: "I'll create a shipment for order #XXXXXX with tracking [carrier: number]. Confirm? (yes/no)"

curl -s -X POST "${MAGENTO_BASE_URL}/rest/${MAGENTO_STORE_CODE:-default}/V1/order/${ORDER_ENTITY_ID}/ship" \
  -H "Authorization: Bearer ${MAGENTO_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "notify": true,
    "tracks": [
      {
        "track_number": "1Z999AA10123456784",
        "title": "UPS",
        "carrier_code": "ups"
      }
    ]
  }'

Common carrier_code values: ups, fedex, usps, dhl, custom. To ship without tracking: omit the tracks array or pass "tracks": []. To ship specific items: add "items": [{"order_item_id": 5, "qty": 1}].

Response is the new shipment ID on success.

---

Operation 7: Search Credit Memos

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

Extract: increment_id, order_id, state, grand_total, created_at, items[].sku, items[].qty, items[].row_total

---

Operation 8: Get Credit Memo by ID

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

Note: Do NOT expose refund creation as an agent action. Magento has documented race conditions producing duplicate credit memos. Refunds must be initiated from the Admin UI.

---

Operation 9: Send Order Email (Write — Confirm First)

Confirm: "I'll send the order confirmation email for order #XXXXXX to the customer. Confirm? (yes/no)"

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

Response is true on success.

---

Operation 10: Search Returns (RMA)

Returns are available on Magento Open Source 2.3+. If the endpoint returns 404, the RMA module may not be enabled.

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

Extract: entity_id, increment_id, order_id, status, created_at, items[].sku, items[].qty_requested, items[].reason

---

Operation 11: Get Return by ID

Full return detail:

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

Return shipping labels (if generated):

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

---

Response Formatting

PII note: Fulfillment documents include customer addresses and emails. When displaying to support agents, mask emails (r***@e***.com), show street addresses as "[REDACTED]", and phone numbers as last 4 digits only (***-1234). Show city + state/country for context.

Invoice list:

Invoice #000000001 | paid | $36.39 | 2024-01-15
  Items: Iris Workout Top (WS03-XS-Red) × 1

Shipment list:

Shipment #000000001 | 2024-01-16
  Tracking: UPS 1Z999AA10123456784
  Items: Iris Workout Top × 1

Credit memo:

Credit Memo #000000001 | refunded $36.39 | 2024-01-20
  Items: Iris Workout Top × 1 | $29.00
  Shipping refund: $5.00 | Tax refund: $2.39

---

Error Handling

• "Cannot create invoice" / HTTP 400: Order may already be fully invoiced, or status doesn't allow it. Show the error.
• "Cannot ship order" etc.: Order not in shippable state (check if invoice exists first for some payment methods).
• HTTP 404 on /returns: RMA module may not be enabled on this store.
• Duplicate shipment concern: Always use /order/{id}/ship not /shipment.

---

Decision Table

| User says | Action | |-----------|--------| | "invoices for order 123" | Search invoices by orderid | | "create invoice for order 123" | Confirm → POST /order/123/invoice | | "has order 123 shipped?" | Search shipments by orderid | | "create shipment with UPS tracking XYZ" | Confirm → POST /order/123/ship | | "refund for order 123" | Search credit memos — DO NOT create via API | | "send confirmation email for order 123" | Confirm → POST /orders/123/emails | | "return request for order 123" | Search returns by order_id |

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.