# VTEX Checkout MCP

> VTEX Checkout MCP lets your AI agent run full e-commerce checkout simulations directly against your VTEX store data. It simulates complete orders, calculates real-time shipping options for any postal code, and applies coupons—all without leaving the chat window. Check client profiles, manage addresses, or validate payments before a customer ever clicks 'Buy.'

## Overview
- **Category:** ecommerce
- **Price:** Free
- **Tags:** cart-simulation, shipping-calculation, checkout-optimization, coupon-management, order-preview, pre-purchase

## Description

This MCP connects your AI agent to your VTEX checkout API, letting you handle complex pre-purchase logic through natural conversation. You can run full order simulations using items and quantities, instantly seeing the total cost and all available shipping options for any ZIP code. Need to check a customer's status? Look up client profiles by user ID or use the tool to manage new shipping addresses. Want to test pricing rules? Apply discount coupons to an active cart and see how much the total drops. You can even simulate payment validations before committing to an order, checking everything in one place. Connecting this through Vinkius makes it available to any compatible AI client, so you get immediate access to deep e-commerce data whether you're using Claude, Cursor, or Windsurf.

## Tools

### create_address
Adds a new physical mailing address record to an existing client profile.

### get_client_profile
Retrieves all contact and identification details for a registered customer using their user ID.

### add_coupon
Applies a specific discount coupon code to an active shopping cart, showing the resulting price drop.

### get_orderform
Pulls all current details and state for a specified order form or shopping cart number.

### simulate_payment
Tests payment tokens to validate whether a specific method will successfully process funds before checkout.

### simulate_order
Runs a comprehensive simulation, calculating the total cost and available shipping methods for a defined set of products.

## Prompt Examples

**Prompt:** 
```
Simulate a cart with 2 units of product ID 1234 and shipping to ZIP 01310-100
```

**Response:** 
```
Cart simulation complete! **Total: R$ 259.80** (2x Widget Pro @ R$ 129.90 each). Shipping options to 01310-100:

🚚 **Standard** — R$ 12.50 (5-7 business days)
⚡ **Express** — R$ 29.90 (1-2 business days)
🆓 **Free Shipping** — eligible (order above R$ 200)
```

**Prompt:** 
```
Apply coupon code SUMMER20 to orderform abc123
```

**Response:** 
```
Coupon **SUMMER20** applied successfully to orderform `abc123`! Discount: **-R$ 51.96 (20% off)**. New total: R$ 207.84. The coupon is now active and will be retained until the order is placed or the cart expires.
```

**Prompt:** 
```
Look up the client profile for user ID 98765
```

**Response:** 
```
Client found: **Maria Silva** (maria@example.com). Document: CPF 123.456.789-00. Phone: +55 11 98765-4321. This client has 3 saved addresses and 12 previous orders.
```

## Capabilities

### Simulate entire orders
Run full cart simulations with specific items and quantities to see the final total, discounts, and shipping costs.

### Manage shopping carts
Fetch the complete details of any active orderform, including items, payment requirements, and client information.

### Apply coupons to carts
Validate discount codes against an active cart and immediately calculate the resulting price change.

### Look up client records
Find a customer's profile using their user ID to retrieve name, contact details, and document numbers.

### Add shipping addresses
Register new physical mailing addresses for clients to ensure accurate checkout flow.

### Validate payments
Test payment tokens and simulate conditions to confirm if a transaction will go through successfully before placing an order.

## Use Cases

### A customer asks for a price quote with multiple items and different tax zones.
The agent runs `simulate_order` using the list of product IDs and the target ZIP code. It returns an immediate, accurate total cost breakdown, including shipping estimates, solving the query in seconds.

### Support needs to verify if a discount coupon was correctly applied.
The agent uses `get_orderform` first to grab the cart ID, then runs `add_coupon` with the code. It confirms not only that the coupon worked but also what the final adjusted total is.

### A new client needs a shipping address saved for future orders.
The agent uses `create_address` with the user's provided details, saving the necessary information to their profile. This means the next time they check out, the address is ready to go.

### Testing if an old payment method will still work for a specific product.
The agent uses `simulate_payment` with the stored token and cart details. It gets instant confirmation of validation status, preventing failed transactions at checkout time.

## Benefits

- Run full order simulations using the `simulate_order` tool. You can test bundles and pricing logic for any postal code without needing to navigate product pages or worry about partial data sets.
- Reduce support friction by letting your agent use `get_client_profile`. Instead of asking a customer to repeat details, you pull their name, CPF/CNPJ, and contact info instantly.
- Test discount rules immediately. The `add_coupon` tool applies codes directly to the cart, showing the precise new total and confirming if the coupon is active or expired.
- Speed up operations by using `get_orderform`. You don't just get a list of items; you get the full state of the cart, including payment conditions and logistics data.
- Enhance customer experience by allowing your agent to use `create_address`, letting support staff register new shipping details right in the conversation flow.

## How It Works

The bottom line is you get deep access to your checkout logic without ever opening the VTEX admin panel.

1. First, subscribe to this MCP and provide your VTEX Account Name, App Key, and App Token from your VTEX Admin settings.
2. Next, instruct your AI agent on the specific checkout task: whether it's simulating a cart for a new product or checking an existing customer's profile.
3. Your agent then executes the required tool call, returning real-time data like total costs, shipping options, and client details directly to you.

## Frequently Asked Questions

**How do I simulate a full order using the VTEX Checkout MCP?**
To start, you call `simulate_order`. You provide the item IDs, quantities, and the target ZIP code. The tool returns a detailed breakdown of all costs, including standard, express, and free shipping options.

**Can I use VTEX Checkout MCP to find out what addresses a customer has saved?**
Yes. While you use `get_client_profile` to get the primary contact details, if you need to register a new one, you run `create_address`. This ensures the client's record is up-to-date.

**What if I want to test multiple coupon codes on one cart?**
You can use the `add_coupon` tool sequentially. You apply the first code, note the new total, and then run it again with the second coupon to see how the cumulative discount impacts the price.

**Does the VTEX Checkout MCP handle payment validation?**
Absolutely. Use `simulate_payment` when you have a token or method on hand. This tool validates that the payment gateway will accept those credentials before the customer attempts to purchase.

**Is this only for active VTEX stores, or can I use it for testing?**
It's designed to handle both. You run complete order simulations even if you aren't placing a live order, making it ideal for pre-launch campaign testing.