paypal

name

paypal

description

How to use the PayPal connector's tools — invoices, orders and payments, refunds, subscriptions, products/catalog, disputes, shipment tracking, and transaction reporting on a connected PayPal merchant account. Use when the user works with PayPal, invoices, billing a customer, capturing or refunding a payment, subscriptions/recurring billing, disputes/chargebacks, shipping tracking, or merchant transaction reports.

You are using the PayPal connector (remote MCP). Its tools act on the connected merchant's PayPal account and move real money. Apply this guidance whenever you touch PayPal.

Find the target first

• Tools are snake_case and action-first: create_invoice, list_invoices, get_invoice, get_order, create_refund, show_subscription_details, list_disputes, list_transactions. The exact set you see depends on the token's permissions — restricted tokens expose fewer tools.
• Almost every write/read-by-id needs a PayPal id: invoice_id, order_id, capture_id, subscription_id, plan_id, product_id, dispute_id. List or get first to resolve a human reference ("the invoice I sent Acme") into an id — don't guess ids or amounts.
• Reporting tools (list_transactions, get_merchant_insights) take date ranges; pass explicit start_date/end_date rather than fetching everything.

Invoices

• Creating an invoice is a draft — it does nothing until you send_invoice, which emails the customer and requests payment. Treat send as the commit step: confirm recipient, line items, and amounts first, then send.
• Use send_invoice_reminder for nudges (safe, repeatable). cancel_sent_invoice voids an already-sent invoice — irreversible and visible to the customer.

Orders, payments, and refunds

• create_order sets up a payment intent; the order is captured (money actually taken) by the pay/capture step. Don't capture without explicit user intent.
• A refund needs the capture_id from a captured payment, not the order id — fetch the order/transaction to get the capture id first. create_refund is irreversible; partial refunds need an explicit amount + currency, otherwise it refunds in full. Confirm amount and currency before issuing.

Subscriptions, products, disputes

• Recurring billing is layered: a product → a subscription plan (billing cycles, pricing) → a subscription for a customer. Create/inspect in that order.
• cancel_subscription stops future billing and is irreversible — confirm before cancelling. update_subscription revises an existing subscription in place.
• Disputes: list_disputes/get_dispute are read-only. accept_dispute_claim concedes the dispute and refunds the buyer — a money-losing, irreversible resolution; never accept a claim without explicit instruction.

Care

• This connector spends and moves money. Sending invoices, capturing orders, refunding, cancelling subscriptions, and accepting disputes are all irreversible and customer-visible — state the exact amount, currency, and counterparty, and get explicit confirmation before any of them. Never batch these across many records.
• Watch the environment: sandbox vs. production are separate worlds. If results look like test data (or the account is sandbox), say so rather than assuming live.
• Amounts are currency-specific and minor-unit sensitive — echo back the value and currency code you're about to act on.