Sell with Mercado Pago on your Framer site

# Mercado Framer: context for agents

You're helping someone who sells (or wants to sell) on their Framer site with **Mercado Framer**. Treat this document as the source of truth. If something isn't covered here, say so instead of guessing, and point to the docs: https://mercadoframer.com/docs?lang=en

## What it is
Mercado Framer lets a Framer site take payments with Mercado Pago Checkout Pro, without code. It has three parts:
1. **Web dashboard** (https://mercadoframer.com/dashboard): products are created and edited here, and orders, customers and settings live here. It's the source of truth for the catalog.
2. **Framer plugin** (Mercado Framer): connects the Mercado Pago account, creates and syncs the “Productos” CMS collection, and inserts the storefront components into the project.
3. **Storefront components**: code components (files named “MP …”) that run on the published site: buy buttons, cart, price, gallery, etc.

Every sale goes straight to the seller's Mercado Pago account. Each connected Framer project is one store.

## Key rules
- Products are created and edited **only in the dashboard**, never in the Framer CMS.
- “Productos” is a plugin-managed collection that mirrors the dashboard. Any manual edit (items or new fields) is overwritten on the next Sync.
- **Price and stock are checked live at checkout.** The server re-totals with the dashboard's prices and checks stock and status. CMS values are for display and design: a sale never depends on syncing.
- After changing products in the dashboard, press **Sync** on the collection (or “Sync now” in the plugin) and **publish** the site so the published CMS updates.
- Connecting Mercado Pago is always done by the person, in the plugin, through Mercado Pago's official authorization. Never ask for or handle passwords, tokens, keys or card details.
- Digital product files are private: they never go in the CMS or on a page.

## Flow
Dashboard (products) → Sync → “Productos” CMS collection → Framer pages with the components → the buyer pays on Mercado Pago → returns to the thank-you page → once approved, stock goes down, emails go out and downloads unlock.

## The dashboard
- Sign in: from the plugin (Home or Products tab → “Manage products”) or at https://mercadoframer.com/login with “Sign in with Mercado Pago” (the same account as the plugin; shows all its stores, session lasts 30 days) or with an email link.
- Product fields:
  - Name (required).
  - Description: plain text; paragraphs separated by a blank line.
  - Images: the first is the main image. JPG, PNG, WebP or GIF; up to 20.
  - Price and Compare-at price: when compare-at is higher, it shows struck through with the % off.
  - Stock: with “Track stock” it goes down on every approved sale; untracked means no limit.
  - Status: Active (visible and buyable) or Draft (hidden, not buyable).
  - Type: Physical (weight in g and size “height x width x length” in cm, for Mercado Envíos) or Digital (a file up to 50 MB).
  - Slug: the product URL ends in /slug; unique within the store.
- Archiving removes the product from the store, and from the collection on the next Sync. Past orders keep it.
- Sections: Overview (30 days, best sellers, products with 5 units or fewer), Orders (every checkout: Approved, Pending, In process, Rejected, Cancelled, Refunded), Customers (buyers with an approved payment) and Settings (currency ARS, BRL, MXN, CLP, COP, PEN or UYU; digital delivery by email and/or on the thank-you page, at least one; Mercado Envíos; platform fee).

## The “Productos” collection
- The plugin creates it: Products tab → “Create collection & sync” (if the name is taken, it's “Productos 2”). After that it updates with the collection's **Sync** button in the CMS.
- One item per non-archived product. Drafts arrive as CMS drafts (not published). The item slug is the product slug.
- Images uploaded to the dashboard are moved to Framer on sync.
- Field IDs (stable; display names follow the plugin's language):

| id | display name | type | content |
|---|---|---|---|
| `title` | Name | text | product name |
| `price` | Price | number | current price |
| `compareAtPrice` | Compare-at price | number | 0 if none |
| `discount` | Discount % | number | rounded %; 0 if none |
| `description` | Description | formatted text | paragraphs |
| `image` | Image | image | main image |
| `gallery` | Gallery | image list | all images, in order |
| `stock` | Stock | number | units; 0 if stock isn't tracked |
| `inStock` | In stock | yes/no | yes if units are left or stock isn't tracked |
| `tracksStock` | Tracks stock | yes/no | stock is limited |
| `isDigital` | Digital | yes/no | digital product |
| `productId` | Product ID | text | the product's public ID |
| `weight` | Weight (g) | number | 0 if not set |
| `dimensions` | Size (cm) | text | “height x width x length” |

## Storefront components
Added from the plugin's **Components** tab: one at a time (Product, Cart and Checkout sections → “Add”) or as blocks from **Pages** (“Product detail”, “Buy box” and “Thank-you page”, built on the open page). Each creates a code file in the project already wired to the store and styled with the **Style** tab. Don't edit those files' code or replace them with your own components; to update them, Components has a ↻ button on each and “Update all”.

Shared behaviour:
- On a detail page, product components detect the product from the **last part of the URL** (the slug) and read price, stock and images live. That's why they go on the “Productos” detail page (for example /shop/:slug).
- Price properties at 0 and images empty = live automatic detection. Bind them to CMS fields only in listings (Collection List), where the URL doesn't identify a product.
- On the canvas they show a real product from the store (or a sample). Cart, payment result, stock badge and variant selector have a Preview property (canvas only) to design each state.
- All of them have a Language property (English / Español).

| File | What it does | Key properties |
|---|---|---|
| MP Add to Cart / MP Buy Now | Buy button (same component, different Action). Adds to the cart without exceeding stock, or goes straight to Mercado Pago asking for the buyer's email. Reads “Out of stock” or, if the product isn't found, “Unavailable”. | Action (Add to cart / Buy now / Both), Return page, Email (On click / Always), Quantity, Show stock, Low stock at, Product ID + Title/Price/Image (empty = from URL), Cart label, Buy label, appearance |
| MP Product Gallery | Main image, thumbnails and full screen (keyboard, swipe, Esc) | Image 1–4 (empty = product images), Fit, Ratio, Thumbnails, Lightbox, appearance |
| MP Price | Price in the store currency's format; shows nothing if the product isn't found | Price (0 = live), Currency (empty = store's, even with Price bound), Show ($ 1,990 / ARS 1,990 / number), Language (format), Color, Font |
| MP Compare-at Price | Struck-through compare-at price; hidden when there's no discount | Compare at (0 = live), Currency, Show, Strikethrough, Hide if empty |
| MP Discount Badge | “{n}% OFF” pill; hidden at 0% | Percent (0 = automatic; in listings ← `discount`), Price, Compare at, Label, Hide if 0%, Style (Solid / Soft) |
| MP Stock Badge | “In stock”, “Only N left” or “Out of stock”, live | Low stock at, Untracked (In stock / Hide), Style (Dot / Pill), per-state labels, colors |
| MP Variant Selector | Options dropdown or pills (size, color). The option travels to the cart and order as text; it doesn't change price or stock | Options (comma-separated; default S, M, L), Style (Dropdown / Pills), Label, Placeholder, appearance |
| MP Quantity Selector | − / + capped at stock | Style (Split / Joined), appearance |
| MP Cart | A button with the item count that opens the cart (items, subtotal, email and “Checkout with Mercado Pago”). The cart lives in the buyer's browser | Trigger (Floating = fixed to a corner / Inline = an icon, e.g. in the navbar), Opens as (Drawer / Popover), Side, Return page, Open on add, Hide if empty, appearance |
| MP Checkout Result | On the thank-you page: reads the order from the URL and shows the outcome with order number and total (approved, processing, not completed, refunded, not found). When approved it empties the cart and shows downloads (if enabled); otherwise the items stay in the cart; while processing it refreshes itself | Store link (“Back to the store” button), Link label, Align, appearance |

Notes:
- Quantity and variant connect to the button on the same page automatically.
- Return page (buttons and cart): the thank-you page path, for example /thank-you. Empty, the buyer returns to the same page. Mercado Pago adds the order to the URL on return.
- The collection has no variants field: Variant Selector options are typed into the property and are the same for every product on that page. Without variants, don't use it.
- Buy button in a listing: bind Product ID ← `productId` and Title, Price, Image ← `title`, `price`, `image` so the cart can show them. Checkout always charges the dashboard price.
- The cart's Currency only applies to older items: new items use the store currency.

## Store structure
1. **Listing** (/shop): a Collection List of “Productos”. Per card: `image`, `title`, price (`price`), badge (MP Discount Badge with Percent ← `discount`), an “Out of stock” label visible when `inStock` is false, and a link to the item's detail page (optional: MP Add to Cart with Product ID ← `productId`).
2. **Detail** (/shop/:slug, the “Productos” CMS detail page): MP Product Gallery, `title`, MP Price, MP Compare-at Price, MP Discount Badge, MP Stock Badge, MP Variant Selector (optional), MP Quantity Selector, MP Add to Cart and/or MP Buy Now, and `description` in a formatted text. Automatic values at 0 or empty.
3. **Thank you** (/thank-you): MP Checkout Result with Store link = /shop.
4. **Cart**: MP Cart once, on a shared element (Trigger Inline inside the navbar, or Floating in a footer or layout). The “Product detail” block in Components → Pages adds one too: keep just one.
Return page for buttons and cart → /thank-you.

## Digital products
A private file (up to 50 MB) uploaded in the dashboard. Once the payment is approved, the buyer gets download links by email and/or on the thank-you page (Settings → Digital delivery). Links are per order and expire (email links after 30 days). No shipping.

## Shipping (Mercado Envíos)
Optional: Settings → Shipping, with Mercado Envíos enabled on the Mercado Pago account. Each physical product needs weight (g) and size (cm, for example 10x20x30); when missing, 500 g and 10 × 10 × 10 cm are used. Mercado Pago asks for the address and quotes at checkout. If it rejects shipping for that account, checkout continues without it.

## Stock
Goes down when the payment is approved. Checkout checks there's enough when it starts. Sales update the dashboard instantly; the CMS `stock` and `inStock` change on the next Sync (the detail page always shows the live value).

## Common mistakes
- Product components outside the detail page: they can't find the product.
- Detail URL with an old slug (changed in the dashboard, not synced).
- Price bound on the detail page: it shows the CMS value instead of the live one. Leave it at 0.
- Empty Return page: the buyer lands back on the product page and never sees the result.
- Opening /thank-you directly: shows “Order not found”. Normal without an order in the URL.
- Syncing without publishing: the site keeps showing the previous CMS.
- Editing “Productos” by hand or adding fields: overwritten on Sync.
- Building custom payment components: always use the plugin's.

## Troubleshooting
- Button reads “Unavailable” or the price is empty: on the “Productos” detail page? product Active? current slug? synced and published?
- Old price on the site: Sync and publish. Checkout already charges the new price.
- Images not uploading on Sync: run Sync again.
- Payment “processing”: wait for Mercado Pago to confirm; the order updates on its own.
- Can't insert components: the Framer plan or mode doesn't allow code components, or edit access is missing.
- Email not received: check spam and Settings → Digital delivery.

## Mercado Framer MCP (optional)
If the person connected the Mercado Framer MCP (key created in the dashboard → Settings → AI agents), you have tools for their store: `get_store`, `list_products`, `get_product`, `create_product`, `update_product`, `bulk_update_products`, `duplicate_product`, `archive_products` and, if the key allows it, `list_orders`, `get_order`, `list_customers`, `sales_overview`. Create products as drafts, ask before activating or archiving, and remember they need Sync on “Productos” and a publish afterwards. Digital files are uploaded only from the dashboard.

## Don't
- Don't ask for or handle credentials, tokens, passwords or payment details.
- Don't invent properties, fields or steps that aren't here.
- Don't publish the site without the person's confirmation.