# VTEX Orders MCP > VTEX Orders MCP gives your AI agent full control over every stage of an e-commerce order, from lookup to cancellation. Use it to search inventory status, track shipments, register invoices, and update fulfillment statuses all through natural conversation. Manage the entire order lifecycle for any VTEX store directly within your favorite AI client. ## Overview - **Category:** ecommerce - **Price:** Free - **Tags:** order-lifecycle, order-tracking, fulfillment, order-invoicing, logistics-management, customer-orders ## Description Managing online orders doesn't have to mean clicking through five different backend tabs just to get a simple status check. This MCP connects your VTEX Order Management System (OMS) straight into your agent, letting you handle the whole order lifecycle using plain conversation. Need to know what happened with an order? You can ask for full details—items, payment method, even logistics info. If a shipment is delayed, you just need to check the tracking number. When it's time to finalize things, you don't have to manually attach tax invoices; your agent handles that and moves the status automatically. This centralized access means whether you’re on a live support call or running end-of-day reports, you can move orders through the fulfillment pipeline with precision. If you need an overview of all pending items, you can search and filter large lists of orders by specific statuses. Because this MCP lives in the Vinkius catalog, you connect once from your preferred AI client—Claude, Cursor, or any compatible agent—and instantly gain full control over your store's operations. ## Tools ### cancel_order Cancels a specific customer order, automatically initiating the refund process if applicable. ### get_order Retrieves complete details for one single, specified order ID. ### register_invoice Attaches tax invoices and tracking numbers to an existing order record. ### search_orders Searches and filters large sets of orders based on criteria like status or date range. ### update_order_status Changes the internal fulfillment status of an order to advance it through the workflow process. ### get_tracking_info Retrieves shipping tracking details, including the carrier and the dedicated tracking URL. ## Prompt Examples **Prompt:** ``` Show me the details of order v-1234567890 ``` **Response:** ``` Order **v-1234567890** found! Status: **Ready for Handling**. 👤 Customer: Maria Silva (maria@example.com) 📦 Items: 2x 'Nike Air Max 90' (SKU: 12345) — R$ 599.90 each 💳 Payment: Credit Card (Visa ending 4321) 🚚 Shipping: PAC (5-7 business days) to CEP 01310-100 **Total: R$ 1,212.30** (including R$ 12.50 shipping). Shall I move it to 'handling'? ``` **Prompt:** ``` List all orders with status 'ready-for-handling' ``` **Response:** ``` Found **23 orders** in 'ready-for-handling' status. Here are the first 5: 1. **v-111** — Maria Silva, R$ 299.90 (1 item) 2. **v-222** — João Souza, R$ 1,450.00 (3 items) 3. **v-333** — Ana Lima, R$ 89.90 (1 item) 4. **v-444** — Pedro Santos, R$ 2,100.00 (2 items) 5. **v-555** — Carla Fernandes, R$ 450.00 (1 item) Would you like to move any of these to 'handling' status? ``` **Prompt:** ``` Cancel order v-444 — customer requested wrong size ``` **Response:** ``` Order **v-444** has been canceled. Reason logged: 'Customer requested wrong size'. The payment refund of R$ 2,100.00 has been automatically initiated via the original payment method (Credit Card). The customer will receive the refund within 5-10 business days. ``` ## Capabilities ### Look up complete order details Retrieve every piece of information about a specific order, including the customer, items purchased, payment type, and current status. ### Search and filter order queues Filter large groups of orders by specific statuses like 'invoiced' or 'ready-for-handling', helping you find exactly what you need fast. ### Advance fulfillment stages Update an order’s internal status, moving it logically through the warehouse process (e.g., from 'ready' to 'handling'). ### Check package tracking information Get real-time carrier data for shipped packages, including the tracking number and direct URL. ### Finalize orders with invoicing Attach necessary tax invoices and shipping numbers to an order, automatically transitioning it into 'Invoiced' status. ### Process cancellations and refunds Cancel an entire order using natural language prompts, triggering the automatic refund process based on the original payment method. ## Use Cases ### A customer calls asking where their package is. The agent doesn't waste time copying IDs. They ask the MCP to use `get_tracking_info`, which immediately pulls the carrier, tracking number, and link into the chat window for the customer. ### The fulfillment team needs to process 50 orders daily. Instead of clicking through 50 different records to mark them as 'handled', the agent uses `search_orders` to pull all pending items, and then runs a batch status update via `update_order_status`, logging progress for everyone. ### A customer reports an item was wrong size. The support agent simply tells the MCP: 'Cancel order v-444.' The system uses `cancel_order` to process the cancellation and automatically initiates the refund, keeping a clear audit trail. ### End of day reporting on paid orders. The operations manager asks for all orders that need final tax documentation. The agent runs `search_orders` by status (e.g., 'pending invoicing') and then uses `register_invoice` to finalize them all in bulk. ## Benefits - Cut down on manual status checks. Instead of navigating the VTEX Admin to manually change a record, your agent uses `update_order_status` and handles it instantly via chat. - Handle refunds and cancellations in one go. Use `cancel_order` to process an entire order cancellation, logging reasons and triggering payment reversals without leaving the conversation. - Stop searching through massive spreadsheets for status updates. The `search_orders` tool lets you filter thousands of records by criteria like 'ready-for-handling' instantly. - Accelerate invoicing. When goods ship, use `register_invoice` to attach tax documents and tracking numbers simultaneously, moving the order straight to 'Invoiced' status. - Get a full picture every time. If a customer asks about an ID, you get everything they need—items, payment, logistics—using `get_order` in seconds. ## How It Works The bottom line is you manage complex e-commerce logistics using only conversation, without ever opening a backend dashboard. 1. First, you subscribe to this MCP within Vinkius and provide your VTEX Account Name, App Key, and App Token from your store's Admin settings. 2. Next, you connect your preferred AI client—like Claude or Cursor—to the catalog. Your agent now has access to all order management tools. 3. Finally, tell your agent what you need done: 'Show me the tracking for v-1234567890' or 'Cancel this order and refund the customer.' The MCP executes the task. ## Frequently Asked Questions **How do I find out what happened to an order using the VTEX Orders MCP?** You use `get_order` to pull up all details for any specific ID. This shows you the customer, items, payment method, and current status in one comprehensive report. **Can the VTEX Orders MCP handle bulk status updates?** Yes, you can use `search_orders` to filter a large list of orders by specific statuses. Then, your agent can batch update those records using `update_order_status`. **Does the VTEX Orders MCP automatically process refunds?** Yes, when you use `cancel_order`, it triggers the automatic refund process against the original payment method, saving you the manual reconciliation steps. **What tools do I need to finalize an order for accounting?** You should use `register_invoice` after confirming shipment. This tool attaches tax invoices and tracking numbers, moving the order into its 'Invoiced' status. **How accurate is the shipping tracking info from the VTEX Orders MCP?** The agent uses `get_tracking_info` to pull data directly from the carrier. It provides the official tracking number and URL for real-time updates.