Agent toolkit

Last updated: Apr 24th, 10:07am

PayPal's agent toolkit is a library that incorporates PayPal API capabilities into AI agent workflows. This toolkit enables popular agent frameworks, such as OpenAI's Agents SDK, Vercel's AI SDK, Model Context Protocol (MCP), LangChain, and CrewAI, to integrate with PayPal APIs using function calling.

Key features

The agent toolkit from PayPal enables you to:

Integrate with PayPal APIs to access orders, invoices, subscriptions, shipment tracking, transaction details, and dispute management through pre-built functions.

Develop with your preferred tools, including:
- AI agent frameworks, like OpenAI's Agents SDK, Vercel's AI SDK, Model Context Protocol (MCP), LangChain, and CrewAI
- Multiple languages, including TypeScript and Python

Build custom agent capabilities to extend core PayPal features and connect with other toolkits to create multi-step agent workflows.

Set up your environment

To prepare for an integration, set up your environment first.

Download and install Node.js version 18 or later from the official Node.js website.

Run the command npm install @paypal/agent-toolkit to install the agent toolkit, or download the package from the GitHub repo.

You'll need your PayPal account's client ID and secret from PayPal Developer Dashboard to configure this library.

Integration

PayPal's agent toolkit supports OpenAI’s Agents SDK, Vercel’s AI SDK, and Model Context Protocol (MCP). It works with LLM providers that supports function calling and is compatible with TypeScript and Python.

For integration steps, see the corresponding topic for your AI platform in this guide.

For information about setting up the front end for testing any of these integrations, see the agent toolkit quickstart guide .

Complete the following steps to integrate PayPal's agent toolkit with OpenAI's Agents SDK. The agent toolkit works with Agents SDK, which passes it as a list of tools.

Import PayPal’s agent toolkit into your code.

Update your clientId and clientSecret with the values from PayPal Developer Dashboard.

1from paypal_agent_toolkit.openai.toolkit import PayPalToolkit
2from paypal_agent_toolkit.common.configuration import Configuration, Context
3
4configuration = Configuration(
5    actions={
6        "orders": {
7            "create": True,
8            "get": True,
9            "capture": True,
10        }
11    },
12    context=Context(
13        sandbox=True
14    )
15)
16
17# Initialize toolkit
18toolkit = PayPalToolkit(client_id=PAYPAL_CLIENT_ID, secret=PAYPAL_SECRET, configuration = configuration)

3. You can use the agent toolkit's functions and other tools as your integration requires.

1from agents import Agent
2
3tools = toolkit.get_tools()
4
5agent = Agent(
6    name="PayPal Assistant",
7    instructions="""
8    You're a helpful assistant specialized in managing PayPal transactions:
9    - To create orders, invoke create_order.
10    - After approval by user, invoke capture_order.
11    - To check an order status, invoke get_order_status.
12    """,
13    tools=tools
14)

Test the integration.

Available tools

PayPal's agent toolkit includes the following tools. We also provide some best practices for prompts and some examples of multistep prompts for common use cases after the lists of 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 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 (e.g., USD, EUR)	Place an order for {quantity} units of '{item_name}' at ${unit_price} each.
`get_order`	Retrieve the details of an order.	`order_id` (string): The unique identifier of the order	Get details for order {order_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}.

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}.

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 last {days} days.

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` (array, optional): The subscriber request 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`	Creates a new subscription plan.	`product_id` (string, required): The name of the subscription plan `name` (string, required): The plan name `billing_cycles` (array, required): An array of billing cycles for trial billing and regular billing. A plan can have at most 2 trial cycles and only 1 regular cycle. `tenure_type` (string, required): The type of billing cycle: `[REGULAR\|TRIAL]` `sequence` (integer, required): The order in which to run this cycle among other billing cycles `frequency` (integer, required): The frequency details for this billing cycle `interval_unit` (string, required): The interval at which the subscription is charged or billed: `[DAY\|WEEK\|MONTH\|YEAR]` `payment_preferences` (array, required): The payment preferences for a subscription `auto_bill_outstanding` (boolean, optional): Indicator of whether to automatically bill the outstanding amount in the next billing cycle. The default value is 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 specific page number to retrieve. The fault behavior is to go to the first page. `page_size` (number, optional): The maximum number of products to return for each page. The default behavior is to use a 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}.

Best practices for prompt engineering

Principle	Usage
Be clear about what to do and how to do it.	Put the action first (“Create an invoice…”), then supply parameter values in the order the tool expects.
Be specific.	Include every required field, such as `currency` and `invoice_id`. Unclear input can cause failure.
Separate complex tasks into simple ones.	For example, if you want to create a checkout sequence, you might have three subtasks: Create order. Pay order. Create shipment.
Encourage the agent to "think."	Begin an analytic request with a statement like “Think step-by-step before calling the tool…”. This can help the agent to avoid making bad calls.
Protect personally identifiable information (PII).	Never embed card numbers, personal financial information like social security numbers (SSNs), passwords, or secrets in prompts. The agent toolkit will reject this information, and you might violate the Payment Card Industry Data Security Standard (PCI DSS).

Multistep agent prompt examples

The following examples provide ideas for how to form multistep prompts for some standard use cases.

Invoice a client

To invoice a client, you might have steps like these:

create_invoice: Create an invoice for jane@example.com for 3 hours of CAD design at $100 per hour.

send_invoice: Send invoice {invoice_id} to the client.

send_invoice_reminder: Send a reminder for invoice {invoice_id}.

Create an online order with payment and tracking

For an online order with shipping, you might use these steps in your prompts:

create_order: Place an order for 2 “Custom Gold Ring” at $450 each (currency USD).

pay_order: Capture payment for order {order_id}.

create_shipment_tracking: Add tracking 1Z999AA10123456784 with carrier UPS to order {order_id}.

Sell a subscription

Subscriptions are a type of product, which come with specific parameters. To sell subscriptions, you might complete these tasks using your agent tools:

create_product: Create a new product named “Coffee-Club Subscription” with the type of DIGITAL.

create_subscription_plan: Create a MONTH subscription plan for product {product_id} named “Monthly Roast Plan” at the price of 20 USD per month.

create_subscription: Create a subscription to plan {plan_id} for subscriber Alice Brown whose email address is alice@example.com.

Evaluate and resolve disputes

To manage disputes, you might use prompts like these:

list_disputes: List all OPEN disputes.

get_dispute: Get details for dispute {dispute_id}.

accept_dispute_claim: Accept the dispute with ID {dispute_id}.

Add and confirm the details for a new product

When you add a new product, you'll want to confirm that the product appears where and how it should. These prompts would do that:

create_product: Create a new product called “Limited-Edition Walnut Serving Tray” of type PHYSICAL.

list_product: List all products (page 1, page_size 25).

show_product_details: Show the details for product {product_id}.

Create an invoice and use a QR code for payment

This example shows how to invoice a client and use a QR code for on-site payment. To complete this sort of process, you might use the following tools and steps:

create_invoice: Create an invoice for bob@example.com for one 1 “Pop-up Booth Entry Fee” at 20 USD.

send_invoice: Send invoice {invoice_id}.

generate_invoice_qr_code: Generate a QR code for invoice {invoice_id}.

Fix an invoice error

To correct an invoice error, might require steps like these:

cancel_sent_invoice: Cancel the SENT invoice with ID {invoice_id}.

create_invoice: Create a corrected invoice for dana@example.com: 4 h consulting at 90 USD/h.

send_invoice: Send invoice {new_invoice_id}.

Reconcile a transaction

To reconcile a transaction, compare the order details to the transaction itself:

list_transaction: List of my transactions for the last 14 days.

get_order: Get the details for order {order_id}.

Cancel a subscription

If a user wants to cancel a subscription, you might need to check the terms of their subscription. To do that, you could use these steps:

show_subscription_details: Show the details for subscription ID {subscription_id}.

cancel_subscription: Cancel the subscription ID {subscription_id}.