AI resources

Commands

The Mercado Pago CLI provides commands to operate our main integrable products directly from the terminal. Check the commands available by product, how to use them, and the complete reference for each one.

Commands by product

Command	Availability by product(s)
`mpcli payments`, `mpcli cards`	Checkout API
`mpcli advanced-payments`	Checkout API
`mpcli preferences`	Checkout Pro
`mpcli orders`	Checkout Pro Checkout API
`mpcli merchant-orders`	Marketplace
`mpcli subscriptions`, `mpcli subscription-plans`	Subscriptions
`mpcli pos`, `mpcli stores`	Point QR code
`mpcli shipping`	Shipping
`mpcli chargebacks`	All products.
`mpcli reports releases`, `mpcli reports settlements`	All products.
`mpcli oauth`	All products.

How to use commands

All CLI commands follow the pattern mpcli [resource] [action] [flags]. You can check the available options for any command using the --help flag:

bash
mpcli --help
mpcli payments --help

Output format

By default, all commands return a JSON:

bash
mpcli payments list
# { "status": "success", "data": { "results": [...] } }

For a readable tabular output, use the --table flag. See an example below:

text
$ mpcli payments list --table
ID            STATUS    AMOUNT   METHOD          DATE
12345678      approved  $ 99.90  account_money   2025-01-01T...

Global flags

Any command accepts the following flags to control output format, authentication, or specific interactive behavior. See the details for each one below:

Flag	Shortcut	Description
`--table`	—	Formatted tabular output.
`--silent`	`-s`	Suppress spinners and ANSI colors.
`--verbose`	`-v`	Display HTTP headers.
`--profile`	`-p`	Credentials profile to use.
`--idempotency-key`	—	Idempotency key for POST/PUT.
`--data`	—	Request body via `JSON` file (`@payload.json`).
`--no-interactive`	—	Disable prompts (CI/CD).
`--no-color`	—	Disable colored output.

Exit codes

In scripts and pipelines, the Mercado Pago CLI returns an exit code at the end of each execution. Use these values to handle errors programmatically:

Code	Meaning
`0`	Success.
`1`	General error.
`2`	Authentication error.
`3`	Validation error.
`4`	Rate limit.

To open the API Reference for any product directly in the browser, use mpcli docs [product] — for example, mpcli docs payments.

Command reference

Payments

Manages the full payment lifecycle, from creation to capture, cancellation, and update.

bash
mpcli payments list
mpcli payments get <id>
mpcli payments search --status approved
mpcli payments search --payment-method-id pix
mpcli payments search --external-reference "ORDER-001"
mpcli payments create --data @payment.json
mpcli payments cancel <id>
mpcli payments capture <id>
mpcli payments update <id> --data @update.json

Refunds

Queries the history and details of refunds associated with a payment, and creates full or partial refunds. You must provide the original payment ID to use this command.

bash
mpcli refunds create <payment-id>
mpcli refunds create <payment-id> --amount 50.00
mpcli refunds list <payment-id>
mpcli refunds get <payment-id> <refund-id>

Advanced Payments

Creates and manages advanced payment flows with split payments and disbursements.

bash
mpcli advanced-payments create --data @advanced_payment.json
mpcli advanced-payments get <id>
mpcli advanced-payments search --external-reference ORDER-001
mpcli advanced-payments update <id> --data @update.json
mpcli advanced-payments refund <id>
mpcli advanced-payments refund <id> --amount 100.00

Checkout Pro Payment Preferences

Creates and manages payment preferences that configure Checkout Pro behavior for each transaction.

bash
mpcli preferences list
mpcli preferences get <id>
mpcli preferences create --data @pref.json
mpcli preferences update <id> --data @pref.json

Customers and Cards

Manages customer profiles and their tokenized cards, enabling recurring charges and payment flows with saved data.

bash
mpcli customers list
mpcli customers get <id>
mpcli customers create --email user@example.com
mpcli customers update <id> --data @customer.json
mpcli customers delete <id>

Subscription Management

Creates and manages recurring plans and subscriptions for periodic charges. See the subscription plans documentation for more information.

bash
mpcli subscriptions list
mpcli subscriptions get <id>
mpcli subscriptions create --data @subscription.json
mpcli subscriptions update <id> --data @sub.json

Stores and Points of Sale (POS)

Creates and configures physical stores and points of sale (POS) to process in-person payments with Point and QR Code. See the QR Code documentation for details on payment processing with orders.

bash
mpcli stores search
mpcli stores get <id>
mpcli stores create --name "Main Store" --external-id MY_STORE
mpcli stores update <id> --data @store.json
mpcli stores delete <id>

Orders

Merchant Orders

Groups payments and shipments in Marketplace flows. Requires Marketplace integration to be configured.

bash
mpcli merchant-orders create --preference-id <preference-id>
mpcli merchant-orders create --data @order.json
mpcli merchant-orders get <id>
mpcli merchant-orders search --external-reference "REF-001"
mpcli merchant-orders update <id> --data @update.json

Shipping

Creates and tracks shipping associated with orders.

bash
mpcli shipping create --data @shipment.json
mpcli shipping get <id>
mpcli shipping list
mpcli shipping cancel <id>
mpcli shipping track <id>

Chargebacks

Financial Reports

Generates and queries financial reports for releases and account money for transaction reconciliation and auditing. See the reports documentation for more information.

The Financial Reports module must be enabled in the Mercado Pago account.

Check the available commands by report type:

bash
mpcli reports releases list
mpcli reports releases create --date-from 2025-01-01 --date-to 2025-01-31

Payment Methods and Identification Types

OAuth

Manages the exchange of authorization codes and renewal of access tokens via OAuth 2.0. See the OAuth documentation for more information.

bash
mpcli oauth url --client-id <id> --redirect-uri https://myapp.com/callback
mpcli oauth token --client-id <id> --client-secret <secret> --code <code> --redirect-uri https://myapp.com/callback
mpcli oauth refresh --token <refresh-token>

Config

Manages named credential profiles to switch between accounts and environments without re-authenticating.

bash
mpcli config set --profile sandbox --token TEST-... --environment sandbox
mpcli config use sandbox
mpcli config list
mpcli config get environment

Sandbox and Testing

Creates and configures test users, virtual balance, and test cards to simulate payment scenarios in the sandbox environment.

Create test user

bash
mpcli tester create

Set virtual balance

bash
mpcli tester balance set --user-id <id> --amount 10000

Provision test card

The --scenario defines the simulated behavior:

bash
mpcli tester card create --user-id <id> --scenario approved
mpcli tester card create --user-id <id> --scenario insufficient_funds
mpcli tester card create --user-id <id> --scenario stolen_card
mpcli tester card create --user-id <id> --scenario high_risk

Scenario	Behavior
`approved`	Card always approved.
`insufficient_funds`	Declined due to insufficient balance.
`stolen_card`	Declined due to invalid security code.
`high_risk`	Enters fraud review.