Agent tools reference

PayPal’s agent toolkit includes the following tools.

Catalog management

Functionality	Description	Parameters	Sample Prompt
create_product	Create a new product in the PayPal catalog.	name (string, required): The name of the product. type (string, required, enum): The type of the product. Allowed values are 'PHYSICAL', 'DIGITAL', 'SERVICE'.	Create a new product with the name {product_name} of type {product_type}.
list_product	List products from the PayPal catalog. Pagination options are available.	page (number, optional): The specific page number to retrieve. The default behavior is to go to the first page. page_size (number, optional): The maximum number of products to return per page. The default behavior is to use a system-defined limit.	List all products.
show_product_details	Show details of a specific product from the PayPal catalog.	product_id (string, required): The ID of the product to retrieve.	Show the details for product id {product_id}.

Dispute management

Functionality	Description	Parameters	Sample Prompt
list_disputes	Retrieve a summary of all disputes with optional filtering.	status (string, optional): Filter disputes by status, such as OPEN or RESOLVED.	List all {status} disputes.
get_dispute	Retrieve detailed information about a specific dispute.	dispute_id (string): The unique identifier of the dispute.	Get details for dispute {dispute_id}.
accept_dispute_claim	Accept a dispute claim, resolving it in favor of the buyer.	dispute_id (string): The unique identifier of the dispute.	Accept the dispute with ID {dispute_id}.

Invoices

Functionality	Description	Parameters	Sample Prompt
create_invoice	Create a new invoice in the PayPal system.	recipient_email: Email address of the invoice recipient. items: List of items or services to include in the invoice: - name (string): Name of the item. - quantity (number): Quantity of the item. - unit_price (number): Price per unit of the item.	Create an invoice for {customer_email} including 2 hours of consulting at $150 per hour.
list_invoices	List invoices. Pagination and filtering options are available.	page (number, optional): Page number for pagination. page_size (number, optional): Number of invoices per page. status (string, optional): Filter invoices by status (such as SENT or PAID).	List all {status} invoices on page {page} with {page_size} invoices per page.
get_invoice	Retrieve details about a specific invoice.	invoice_id (string): The unique identifier of the invoice.	What are the details of invoice {invoice_id}?
send_invoice	Send an existing invoice to the specified recipient.	invoice_id (string): The unique identifier of the invoice to be sent.	Send invoice {invoice_id} to the client.
send_invoice_reminder	Send a reminder for an existing invoice.	invoice_id (string): The unique identifier of the invoice.	Send a reminder for invoice {invoice_id}.
cancel_sent_invoice	Cancel a sent invoice.	invoice_id (string): The unique identifier of the invoice to cancel.	Cancel the sent invoice {invoice_id}.
generate_invoice_qr_code	Generate a QR code for an invoice.	invoice_id (string): The unique identifier of the invoice.	Generate a QR code for invoice {invoice_id}.

Payments

Functionality	Description	Parameters	Sample Prompt
create_order	Create an order in the PayPal system based on the provided details.	items (array): List of items to include in the order each item should have: - name (string): Name of the item. - quantity (number): Quantity of the item. - unit_price (number): Price per unit of the item. currency (string): Currency code, such as USD or EUR.	Place an order for {quantity} units of '{item_name}' at ${unit_price} each.
create_refund	Process a refund for a captured payment.	capture_id (string): The unique identifier of the captured payment to refund. amount (number, optional): The refund amount. If not specified, a refund is for the full amount of the purchase. currency (string, optional): Currency code for the refund, such as USD or EUR.	Process a refund for capture {capture_id}. Process a refund for order {order_id}.
get_order	Get details of a specific payment.	payment_id (string, required)	What are the details of payment {payment_id}?
get_refund	Get the details for a specific refund.	refund_id (string): The unique identifier of the refund.	Get details for refund {refund_id}.
pay_order	Capture payment for an authorized order.	order_id (string): The unique identifier of the order to capture.	Capture payment for order {order_id}.

Reporting and insights

Functionality	Description	Parameters	Sample Prompt
get_merchant_insights	Retrieve business intelligence metrics and analytics for a merchant, filtered by start date, end date, insight type, and time interval.	start_date (string, required): The start date range to filter insights. end_date (string, required): The end date range to filter insights. insight_type (str, required): The type of insight to retrieve. It can be "ORDERS" or "SALES" time_interval (str, required): The time periods used for segmenting metrics data. It can be "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", or "YEARLY"	Give me insights on my sales data from 01/01/2025 to 02/01/2025 using daily time intervals.
list_transaction	List all transactions. Pagination and filtering options are available.	start_date (string, optional): The start date for filtering transactions. The default value is 31 days. end_date (string, optional): The end date for filtering transactions.	Get the list of my transactions for the last {days} days.

Shipment tracking

Functionality	Description	Parameters	Sample Prompt
create_shipment_tracking	Create shipment tracking information for a PayPal transaction.	tracking_number (string, required): The tracking number for the shipment. transaction_id (string, required): The transaction ID associated with the shipment. carrier (string, required): The carrier handling the shipment, such as FEDEX or UPS. order_id: (string, optional): The order ID for the shipment. status: (string, optional, enum): The current status of the shipment. Allowed values are ["ON_HOLD", "SHIPPED", "DELIVERED", "CANCELLED", "LOCAL_PICKUP"]. The default value is "SHIPPED".	Add tracking number '{tracking_number}' with carrier '{carrier}' to PayPal order ID {order_id}.
get_shipment_tracking	Get shipment tracking information for a specific shipment.	order_id (string, required): The order ID for the shipment. transaction_id (string, optional): The transaction ID associated with the shipment.	Get the tracking number for PayPal order ID {order_id}.
update_shipment_tracking	Update shipment tracking information for a specific shipment.	transaction_id (string, required): The transaction ID for the shipment. tracking_number (string, required): The tracking number for the shipment that you want to update. new_tracking_number (string, optional): The new tracking number for the shipment if you’re updating its tracking number. status (string, required): The status of the shipment. It can be "CANCELLED", "DELIVERED", "LOCAL_PICKUP", "ON_HOLD", or "SHIPPED". carrier (string, optional): The carrier that is handling the shipment, such as FEDEX or UPS.	Update the shipment tracking info for transaction_id '{transaction_id}' with tracking number '{tracking_number}' and status '{status}' to carrier '{carrier}' and use the new_tracking_number '{new_tracking_number}'.

Subscription management

Functionality	Description	Parameters	Sample Prompt
cancel_subscription	Cancel an active subscription.	subscription_id (string, required): The ID of the subscription to cancel. reason (string, optional): Cancellation reason.	Cancel the subscription id {subscription_id}.
create_subscription	Create a new subscription.	plan_id (string, required): The ID of the subscription plan. subscriber (object, optional): The subscriber information: - name (string, optional): The name of the subscriber. - email (string, optional): The email address of the subscriber.	Create a subscription for plan id {plan_id} with subscriber name as {subscriber_name} with email address {subscriber_email}.
create_subscription_plan	Create a new subscription plan.	product_id (string, required): The ID of the product. name (string, required): The plan name. billing_cycles (array, required): An array of billing cycles for trial and regular billing. A plan can have at most 2 trial cycles and only 1 regular cycle: - tenure_type (string, required): [REGULAR|TRIAL]. - sequence (integer, required): The order of this cycle. - frequency (integer, required): Frequency details. - interval_unit (string, required): [DAY|WEEK|MONTH|YEAR]. payment_preferences (object, required): Payment preferences for the subscription. auto_bill_outstanding (boolean, optional): Automatically bill outstanding amount (default: true).	Create a {interval_unit} PayPal subscription plan for product ‘{product_name}’ with billing cycle ‘{billing_cycle}’, price ‘{price} {currency}’. Set trial period cycle to ‘{trial_period}’.
list_subscription_plans	List subscription plans.	product_id (number, optional): List the subscription plans for a specific product. page (number, optional): The page number to retrieve (default: first page). page_size (number, optional): The maximum number of products to return per page (default: system-defined limit).	List all subscription plans.
show_subscription_details	Show details of a specific subscription.	subscription_id (string, required): The ID of the subscription to retrieve.	Show the details for subscription id {subscription_id}.
show_subscription_plan_details	Show details of a specific subscription plan.	billing_plan_id (string, required): The ID of the subscription plan to retrieve.	Show the details for plan id {billing_plan_id}.
update_subscription	Update an existing subscription.	subscription_id (string, required): The ID of the subscription to update.	Update the PayPal subscription ID {subscription_id} to billing cycle {billing_cycle} and price {price}.

Additional tools for remote MCP server

PayPal’s remote MCP server offers more tools for product search and checkout using PayPal for payments. These tools are for gift cards only for now, but more is coming soon.

To use these tools in your MCP client, you provide an extra argument. For example, if you are using Claude, add a header parameter, as shown in the following example.

{
  "mcpServers": {
    "paypal-commerce-ai": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.paypal.com/sse",
        //Pass additional header parameter to see the commerce tools. 
        "--header",
        "x-feature-flags: commerce:true"
      ]
    }
  }
}

Functionality	Description	Sample prompt
search_product	Find gift card products in the PayPal catalog. This tool searches the catalog for gift cards that meet your criteria. It returns product information that includes pricing, availability, and purchase options.	Find available gift cards. Show me gift cards that cost less than $50.
create_cart	Open a new shopping cart with specified items and shipping preferences. This tool creates a new shopping cart with the selected gift cards. It handles cart initialization, item configuration, and preparing the cart for checkout.	Add a $50 gift card to my cart.
checkout_cart	Finalize a shopping cart to complete the purchase process. This tool processes the final checkout for a configured shopping cart using PayPal for payment. It handles payment processing, transaction validation, and purchase confirmation.	Complete checkout for my current cart using PayPal.