A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The PayPal API is how an app or AI agent works with a PayPal business account: creating a checkout order, capturing or refunding a payment, billing a subscriber, sending an invoice, or paying out to many recipients at once. Access is granted through an app's client ID and secret, which are exchanged for a short-lived access token, and what that token can do is set by the features and products enabled on the app rather than fine-grained per-call permissions. A change in an account emits an event that PayPal can deliver to a registered endpoint.
How an app or AI agent connects to PayPal determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes PayPal tools to agents, and each is governed by the app credentials behind it and the features enabled on that app.
The REST API takes JSON request bodies and returns JSON, at https://api-m.paypal.com for production and https://api-m.sandbox.paypal.com for testing. A call authenticates with an OAuth 2.0 access token in the Authorization header. Each API carries its version in the path, like the v2 checkout and payments APIs and the v1 billing, payouts, and catalog APIs.
PayPal POSTs an event object to an HTTPS endpoint registered for the app. The receiver verifies the event by calling the verify-webhook-signature API or by checking the transmission signature headers against the webhook's ID and PayPal's certificate, which confirms the request came from PayPal. PayPal asks integrations to rely on webhooks rather than polling.
A first-party Model Context Protocol server exposes PayPal tools to AI agents and LLM clients, at https://mcp.paypal.com for production and https://mcp.sandbox.paypal.com for sandbox, over server-sent events or streamable HTTP. It authenticates with the app's client ID and secret passed as a Bearer token, and restricts which tools a client sees to those the token permits. It covers areas like invoices, orders, subscriptions, products, shipment tracking, transactions, and disputes.
An app exchanges its client ID and secret for a short-lived access token at the OAuth token endpoint, sending grant_type=client_credentials with the credentials Base64-encoded in a Basic auth header. The token is then sent as a Bearer token on every API call. Tokens last several hours, and PayPal asks integrations to cache and reuse them rather than minting a new one per request.
What an access token can do is set by the features and products enabled on the app in the developer dashboard, like Accept Payments, Payouts, or Invoicing, rather than fine-grained scopes chosen per call. The token response lists the scopes the app currently carries, which reflect those enabled features. Enabling a sensitive product, such as Payouts, often requires a separate approval from PayPal.
The PayPal REST API is split into areas an agent can act on, like checkout orders, payments, subscriptions, invoices, payouts, and the product catalog. Each area has its own methods, and writes in some areas move real money or send money to other people.
Methods for creating and processing checkout orders.
Methods for authorizations, captures, and refunds after checkout.
Methods for billing plans and recurring subscriptions.
Methods for creating, sending, and managing invoices.
Methods for sending money to one or many recipients in a batch.
Methods for the products that subscriptions and plans reference.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Orders (Checkout)Methods for creating and processing checkout orders.7 | ||||||
| POST | /v2/checkout/orders | Create an order to start a checkout, choosing immediate capture or authorize-then-capture. | write | Orders write | Current | |
Needs the Accept Payments feature enabled on the app. The intent field selects CAPTURE or AUTHORIZE. Acts onorder Permission (capability) Orders writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/checkout/orders/{id} | Show details for an order, by ID. | read | Orders read | Current | |
Read-only. Acts onorder Permission (capability) Orders readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/checkout/orders/{id} | Update an order, for example its amount or shipping, before it is captured. | write | Orders write | Current | |
Uses JSON Patch operations; only certain fields are patchable before approval. Acts onorder Permission (capability) Orders writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/checkout/orders/{id}/confirm-payment-source | Attach and confirm the payment source on an order before it is authorized or captured. | write | Orders write | Current | |
Used in flows where the integration collects the payment source rather than redirecting the buyer. Acts onorder Permission (capability) Orders writeVersionAvailable since the API’s base version Webhook event CHECKOUT.ORDER.APPROVEDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/checkout/orders/{id}/authorize | Authorize payment for an order, placing a hold on the buyer's funds to capture later. | write | Orders write | Current | |
An authorization holds funds and is valid for 29 days. The order must use intent AUTHORIZE. Acts onauthorization Permission (capability) Orders writeVersionAvailable since the API’s base version Webhook event PAYMENT.AUTHORIZATION.CREATEDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/checkout/orders/{id}/capture | Capture payment for an approved order, settling the funds. | write | Orders write | Current | |
Moves real money. The buyer must have approved the order, or a valid payment source must be supplied. Acts oncapture Permission (capability) Orders writeVersionAvailable since the API’s base version Webhook event CHECKOUT.ORDER.COMPLETEDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/checkout/orders/{id}/track | Add shipment tracking information to an order. | write | Orders write | Current | |
Records a carrier and tracking number against the order. Acts ontracker Permission (capability) Orders writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PaymentsMethods for authorizations, captures, and refunds after checkout.7 | ||||||
| GET | /v2/payments/authorizations/{authorization_id} | Show details for an authorized payment, by ID. | read | Payments read | Current | |
Read-only. Acts onauthorization Permission (capability) Payments readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/payments/authorizations/{authorization_id}/capture | Capture funds against an existing authorization, fully or partially. | write | Payments write | Current | |
Moves real money. Captures held funds before the authorization expires. Acts oncapture Permission (capability) Payments writeVersionAvailable since the API’s base version Webhook event PAYMENT.CAPTURE.COMPLETEDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/payments/authorizations/{authorization_id}/reauthorize | Reauthorize a payment to extend the hold after the initial honor period passes. | write | Payments write | Current | |
Used to keep an authorization valid before capturing later. Acts onauthorization Permission (capability) Payments writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/payments/authorizations/{authorization_id}/void | Void an authorization, releasing the hold so the funds are not captured. | write | Payments write | Current | |
Releases the held funds back to the buyer. Acts onauthorization Permission (capability) Payments writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/payments/captures/{capture_id} | Show details for a captured payment, by ID. | read | Payments read | Current | |
Read-only. Acts oncapture Permission (capability) Payments readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/payments/captures/{capture_id}/refund | Refund a captured payment, fully or partially. | write | Payments write | Current | |
Moves real money back to the buyer. Acts onrefund Permission (capability) Payments writeVersionAvailable since the API’s base version Webhook event PAYMENT.CAPTURE.REFUNDEDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/payments/refunds/{refund_id} | Show details for a refund, by ID. | read | Payments read | Current | |
Read-only. Acts onrefund Permission (capability) Payments readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Subscriptions & BillingMethods for billing plans and recurring subscriptions.7 | ||||||
| POST | /v1/billing/plans | Create a billing plan that defines pricing and billing cycles for subscriptions. | write | Subscriptions write | Current | |
A plan references a catalog product and is the template a subscription is created from. Acts onplan Permission (capability) Subscriptions writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/billing/plans | List billing plans. | read | Subscriptions read | Current | |
Read-only. Acts onplan Permission (capability) Subscriptions readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/billing/subscriptions | Create a subscription against a billing plan for recurring payments. | write | Subscriptions write | Current | |
Starts the recurring billing relationship; the subscriber usually approves it first. Acts onsubscription Permission (capability) Subscriptions writeVersionAvailable since the API’s base version Webhook event BILLING.SUBSCRIPTION.CREATEDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/billing/subscriptions/{id} | Show details for a subscription, by ID. | read | Subscriptions read | Current | |
Read-only. Acts onsubscription Permission (capability) Subscriptions readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/billing/subscriptions/{id}/cancel | Cancel a subscription so it stops billing the subscriber. | write | Subscriptions write | Current | |
Ends recurring billing; a reason can be supplied. Acts onsubscription Permission (capability) Subscriptions writeVersionAvailable since the API’s base version Webhook event BILLING.SUBSCRIPTION.CANCELLEDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/billing/subscriptions/{id}/suspend | Suspend a subscription, pausing billing until it is activated again. | write | Subscriptions write | Current | |
A reason can be supplied; billing resumes on activate. Acts onsubscription Permission (capability) Subscriptions writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/billing/subscriptions/{id}/capture | Capture an authorized payment from a subscriber outside the normal cycle. | write | Subscriptions write | Current | |
Moves real money by charging the subscriber. Acts onsubscription Permission (capability) Subscriptions writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvoicingMethods for creating, sending, and managing invoices.6 | ||||||
| POST | /v2/invoicing/invoices | Create a draft invoice. | write | Invoicing write | Current | |
Starts in draft until it is sent. Acts oninvoice Permission (capability) Invoicing writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/invoicing/invoices | List invoices. | read | Invoicing read | Current | |
Read-only. Acts oninvoice Permission (capability) Invoicing readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/invoicing/invoices/{invoice_id} | Show details for an invoice, by ID. | read | Invoicing read | Current | |
Read-only. Acts oninvoice Permission (capability) Invoicing readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/invoicing/invoices/{invoice_id}/send | Send or schedule an invoice to be sent to a customer. | write | Invoicing write | Current | |
Emails the invoice to the recipient and moves it out of draft. Acts oninvoice Permission (capability) Invoicing writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/invoicing/invoices/{invoice_id}/remind | Send a reminder for a sent invoice. | write | Invoicing write | Current | |
Emails the recipient again about an unpaid invoice. Acts oninvoice Permission (capability) Invoicing writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/invoicing/invoices/{invoice_id}/cancel | Cancel a sent invoice. | write | Invoicing write | Current | |
Notifies the recipient that the invoice is cancelled. Acts oninvoice Permission (capability) Invoicing writeVersionAvailable since the API’s base version Webhook event INVOICING.INVOICE.CANCELLEDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PayoutsMethods for sending money to one or many recipients in a batch.4 | ||||||
| POST | /v1/payments/payouts | Create a batch payout to send money to one or many recipients in a single call. | write | Payouts write | Current | |
Sends real money out, up to 15,000 items per call. Needs the Payouts feature enabled on the app. Acts onpayout_batch Permission (capability) Payouts writeVersionAvailable since the API’s base version Webhook event PAYMENT.PAYOUTSBATCH.SUCCESSRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/payments/payouts/{id} | Show the status and items of a payout batch, by ID. | read | Payouts read | Current | |
Read-only. Acts onpayout_batch Permission (capability) Payouts readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/payments/payouts-item/{payout_item_id} | Show details for a single payout item, by ID. | read | Payouts read | Current | |
Read-only; helps identify a denied payment within a batch. Acts onpayout_item Permission (capability) Payouts readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/payments/payouts-item/{payout_item_id}/cancel | Cancel an unclaimed payout item before it is automatically refunded. | write | Payouts write | Current | |
Only applies to items still in unclaimed status. Acts onpayout_item Permission (capability) Payouts writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Catalog ProductsMethods for the products that subscriptions and plans reference.3 | ||||||
| POST | /v1/catalogs/products | Create a catalog product that billing plans can reference. | write | Catalog write | Current | |
A product is the good or service a subscription plan is built on. Acts onproduct Permission (capability) Catalog writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/catalogs/products | List catalog products. | read | Catalog read | Current | |
Read-only. Acts onproduct Permission (capability) Catalog readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/catalogs/products/{product_id} | Update a catalog product's details, by ID. | write | Catalog write | Current | |
Uses JSON Patch operations to change fields like description or image URL. Acts onproduct Permission (capability) Catalog writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PayPal can notify an app when something happens in an account, like a buyer approving an order or a payment being captured. It sends an event describing what changed, so an integration learns about activity without polling, which PayPal asks integrations to avoid.
| Event | What it signals | Triggered by |
|---|---|---|
CHECKOUT.ORDER.APPROVED | A buyer approved a checkout order, so it is ready to be authorized or captured. | /v2/checkout/orders/{id}/confirm-payment-source |
CHECKOUT.ORDER.COMPLETED | A checkout order was processed and completed. | /v2/checkout/orders/{id}/capture |
PAYMENT.AUTHORIZATION.CREATED | A payment authorization was created, placing a hold on the buyer's funds. | /v2/checkout/orders/{id}/authorize |
PAYMENT.CAPTURE.COMPLETED | A payment capture completed and the funds settled. | /v2/payments/authorizations/{authorization_id}/capture |
PAYMENT.CAPTURE.REFUNDED | A merchant refunded a payment capture, fully or partially. | /v2/payments/captures/{capture_id}/refund |
BILLING.SUBSCRIPTION.CREATED | A subscription was created. | /v1/billing/subscriptions |
BILLING.SUBSCRIPTION.CANCELLED | A subscription was cancelled and recurring billing stopped. | /v1/billing/subscriptions/{id}/cancel |
INVOICING.INVOICE.CANCELLED | A merchant or customer cancelled an invoice. | /v2/invoicing/invoices/{invoice_id}/cancel |
PAYMENT.PAYOUTSBATCH.SUCCESS | A batch payout completed successfully. | /v1/payments/payouts |
PayPal does not publish numeric rate limits. It may temporarily slow an app down if traffic looks abusive, returning a clear error when it does, and it asks integrations to cache tokens and rely on webhooks rather than polling.
PayPal does not publish numeric rate limits. It states that it does not have a published rate-limiting policy but may temporarily rate limit an app if it sees traffic that looks abusive or anomalous. When that happens a call returns HTTP 429 with the error name RATE_LIMIT_REACHED. To stay under the radar, PayPal asks integrations to cache and reuse the OAuth access token rather than minting one per request, and to rely on webhooks instead of polling. A persistent rate-limiting problem is handled through Merchant Technical Support rather than a self-service quota.
List endpoints page through results with parameters that vary by API. The invoicing and subscriptions list endpoints take page and page_size, with total_items and total_pages returned, while other lists use a starting point and a page size; responses include HATEOAS links that point to the next and previous pages.
A single batch payout can carry up to 15,000 items in one call. Invoice item descriptions and similar text fields have their own per-field maximum lengths, documented per request body. An authorization holds funds for up to 29 days before it must be captured or reauthorized.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST | The request is not well-formed, is syntactically incorrect, or violates the schema. The details array names the offending field and issue. | Read the details array, fix the named field, and resend. The request is not retryable as-is. |
| 401 | AUTHENTICATION_FAILURE | Authentication failed, for example an invalid client ID and secret (INVALID_CLIENT) or an expired or invalid access token (INVALID_TOKEN). | Confirm the app credentials, request a fresh access token, and resend. |
| 403 | NOT_AUTHORIZED | Authorization failed due to insufficient permissions, often because the feature or product the call needs is not enabled on the app. | Enable the required feature on the app, or use an app that has it, then resend. |
| 404 | RESOURCE_NOT_FOUND | The requested resource does not exist, or is not visible to this app or environment. | Verify the resource ID and confirm it lives in the same environment, sandbox or live. |
| 422 | UNPROCESSABLE_ENTITY | The request was well-formed but failed a business rule, for example an order in a state that cannot be captured. | Read the details array for the specific issue, correct the business condition, and resend. |
| 429 | RATE_LIMIT_REACHED | Too many requests arrived too quickly, or the traffic looked abusive, so PayPal temporarily rate limited the app. | Back off and retry later, cache the access token, and use webhooks instead of polling. |
| 500 | INTERNAL_SERVER_ERROR | An error occurred on PayPal's side. The debug_id identifies the failure for support. | Retry later with backoff, and contact PayPal support with the debug_id if it persists. |
PayPal versions each REST API in its path, like the v2 checkout and payments APIs and the v1 billing and payouts APIs, and ships dated release notes that add fields and features without breaking existing calls.
PayPal versions each REST API in its path rather than with one account-wide version. Checkout orders and payments are v2; billing plans, subscriptions, payouts, and catalog products are v1. Changes ship through dated, backward-compatible release notes per API.
PayPal expanded its remote Model Context Protocol server to include the full agent-toolkit tool set, with restricted tool visibility so a client and its model see only the tools their token permits.
A backward-compatible Orders v2 update.
PayPal began rolling out a first-party Model Context Protocol server, starting with the Invoice feature for eligible merchants, available as both a local and a remote server.
A backward-compatible Orders v2 update adding payment methods and fields.
A backward-compatible Orders v2 update.
Each API carries its own version in the path; new fields and features arrive through dated, backward-compatible release notes.
PayPal API release notes ↗Bollard AI sits between a team's AI agents and PayPal. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.