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. |
mpcli docs [product] — for example, mpcli docs payments.Command reference
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
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>
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
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
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>
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
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>
Queries orders automatically generated by Mercado Pago when processing a payment via Checkout Pro or Checkout API.
bash
mpcli orders get <id>
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
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>
Queries and tracks chargebacks opened against charges made by your integration.
bash
mpcli chargebacks list mpcli chargebacks get <id> mpcli chargebacks search --payment-id <payment-id>
Generates and queries financial reports for releases and account money for transaction reconciliation and auditing. See the reports documentation for more information.
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
Queries the payment methods and identity document types available for the country configured in the account.
bash
mpcli payment-methods list mpcli identification-types list
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>
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
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. |