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	Process a refund for capture {capture_id}. Process a refund for order {order_id}.
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
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}.

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.