The PayPal connector lets your AI agent work with PayPal. Scalekit handles authentication for every call, so your agent never handles credentials. It comes with 63 tools.
- Tools
- 63
- What they doRead · write · destructive
- 22 · 41 · 022 read41 write0 destructive
- Users sign in with
- Service account
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the PayPal connection
In AgentKit > Connections, create a PayPal connection. The name you give it is the
connection_nameyour code passes. See Configure connections.
Tools
Pass the exact name toexecute_toolpaypal_balances_listList the PayPal account's balances per currency, now or as of a past time within the last three years.Read-onlyList Balances
List the PayPal account's balances per currency, now or as of a past time within the last three years. Returns balances with currency, total_balance, available_balance and withheld_balance, plus as_of_time and last_refresh_time. Use balances_list to check available funds, for example before payout_create. Use transactions_list for the activity behind a balance.
Inputs
as_of_timestring- Return balances as of this ISO 8601 date-time. Defaults to the latest refreshed balance. Example: 2026-10-01T00:00:00Z
currency_codestring- Only the balance in this three-letter currency. Example: USD
paypal_capture_getGet one captured PayPal payment by id, including status, amount, final_capture, seller_receivable_breakdown (gross amount, PayPal fee and net amount) and links.Read-onlyGet Capture
Get one captured PayPal payment by id, including status, amount, final_capture, seller_receivable_breakdown (gross amount, PayPal fee and net amount) and links. Returns the capture object. Use capture_get to check a payment's status or fees before refunding it. Use refund_get for a refund's details.
Inputs
capture_idstringrequired- The PayPal capture ID, found in purchase_units[].payments.captures[].id of the order returned by order_capture or order_get, or returned by authorization_capture. Example: 2GG279541U471931P
paypal_dispute_getGet one dispute by id, including reason, status, disputed transactions, amounts, messages, evidence, offers, seller_response_due_date and allowed_response_options.Read-onlyGet Dispute
Get one dispute by id, including reason, status, disputed transactions, amounts, messages, evidence, offers, seller_response_due_date and allowed_response_options. Returns the dispute object. Use dispute_get before responding to a dispute to see what actions are allowed. Use disputes_list to find dispute ids.
Inputs
dispute_idstringrequired- The PayPal dispute ID (starts with PP-), returned by disputes_list. Example: PP-D-27803
paypal_disputes_listList disputes against the PayPal account (created within the last 180 days by default), optionally filtered by state, transaction or update time.Read-onlyList Disputes
List disputes against the PayPal account (created within the last 180 days by default), optionally filtered by state, transaction or update time. Returns items with dispute_id, reason, status, dispute_state, dispute_life_cycle_stage, dispute_amount and times, plus a next link carrying next_page_token. Use disputes_list to find open disputes. Use dispute_get for one dispute's messages, evidence and allowed responses.
Inputs
dispute_statestring- Only disputes in these states, comma-separated: REQUIRED_ACTION, REQUIRED_OTHER_PARTY_ACTION, UNDER_PAYPAL_REVIEW, RESOLVED, OPEN_INQUIRIES or APPEALABLE. Example: REQUIRED_ACTION,OPEN_INQUIRIES
disputed_transaction_idstring- Only disputes about this PayPal transaction ID. Cannot be combined with start_time. Example: 5TY05013RG002845M
next_page_tokenstring- Token for the next page, taken from the next_page_token parameter in the next link of the previous response. Example: ARt111
page_sizeinteger- Number of items per page, from 1 to 50. PayPal uses 10 when omitted.
start_timestring- Only disputes created on or after this ISO 8601 date-time, within the last 180 days. Cannot be combined with disputed_transaction_id. Example: 2026-07-01T00:00:00.000Z
update_time_afterstring- Only disputes last updated after this ISO 8601 date-time. Example: 2026-10-01T00:00:00.000Z
update_time_beforestring- Only disputes last updated before this ISO 8601 date-time. Example: 2026-10-14T00:00:00.000Z
paypal_invoice_getGet one PayPal invoice by id, including status, detail, invoicer, recipients, line items, amounts, due amount, payments and refunds.Read-onlyGet Invoice
Get one PayPal invoice by id, including status, detail, invoicer, recipients, line items, amounts, due amount, payments and refunds. Returns the invoice object. Use invoice_get to read a known invoice or before invoice_update. Use invoices_search to find invoices by criteria.
Inputs
invoice_idstringrequired- The PayPal invoice ID (starts with INV2-), returned by invoice_create, invoices_list or invoices_search. Example: INV2-Z56S-5LLA-Q52L-CPZ5
paypal_invoice_template_getGet one PayPal invoice template by id, including its name, default flag, prefilled invoice content and field display settings.Read-onlyGet Invoice Template
Get one PayPal invoice template by id, including its name, default flag, prefilled invoice content and field display settings. Returns the template object. Use invoice_template_get before invoice_template_update. Use invoice_templates_list to find template ids.
Inputs
template_idstringrequired- The invoice template ID (starts with TEMP-), returned by invoice_templates_list or invoice_template_create. Example: TEMP-19V05281TU309413B
paypal_invoice_templates_listList the invoice templates in the PayPal account, including PayPal's three system templates and any you created.Read-onlyList Invoice Templates
List the invoice templates in the PayPal account, including PayPal's three system templates and any you created. Returns templates with id, name, default_template and, unless fields is none, the prefilled invoice content. Use invoice_templates_list to find a template_id for invoice creation or invoice_template_get.
Inputs
fieldsstring- all (the default) returns full template details; none returns only each template's name, id and default flag.one of
allnone pageinteger- Page number to return, starting at 1. Defaults to 1. Combine with page_size: page=2 with page_size=20 returns items 21 to 40.
page_sizeinteger- Number of items per page, from 1 to 100. PayPal uses 20 when omitted.
paypal_invoices_listList invoices in the PayPal account one page at a time.Read-onlyList Invoices
List invoices in the PayPal account one page at a time. Returns items with each invoice's id, status, detail (number, dates, currency), primary recipients and amount, plus paging links. Use invoices_list to browse all invoices. Use invoices_search to filter by recipient, status, invoice number, amount or date.
Inputs
pageinteger- Page number to return, starting at 1. Defaults to 1. Combine with page_size: page=2 with page_size=20 returns items 21 to 40.
page_sizeinteger- Number of items per page, from 1 to 100. PayPal uses 20 when omitted.
total_requiredboolean- Set to true to include total_items and total_pages in the response so you know how many pages exist. Defaults to false.
paypal_order_getGet one PayPal order by id, including status, intent, purchase units, payer and any captures or authorizations made against it.Read-onlyGet Order
Get one PayPal order by id, including status, intent, purchase units, payer and any captures or authorizations made against it. Returns the full order object. Use order_get to check whether the buyer approved an order or to find its capture and authorization ids. Use transactions_list to search settled account activity instead.
Inputs
order_idstringrequired- The PayPal order ID returned by order_create (also shown in the buyer's approval URL as the token parameter). Example: 5O190127TN364715T
fieldsstring- Optional extra fields to include. The only supported value is payment_source, which adds the buyer's payment source details.
paypal_payout_getGet the latest status of a batch payout, including batch_header (batch_status, totals and fees) and each item's payout_item_id, transaction_status and amount, one page at a time.Read-onlyGet Payout Batch
Get the latest status of a batch payout, including batch_header (batch_status, totals and fees) and each item's payout_item_id, transaction_status and amount, one page at a time. Returns the payout batch object. Use payout_get to track a batch from payout_create. Use payout_item_get for one item.
Inputs
payout_batch_idstringrequired- The payout_batch_id returned by payout_create. Example: FYXMPQTX4JC9N
pageinteger- Page of items to return, starting at 1. Defaults to 1.
page_sizeinteger- Number of items per page, up to 1000.
total_requiredboolean- Set to true to include total_items and total_pages in the response so you know how many pages exist. Defaults to false.
paypal_payout_item_getGet one payout item by id, including transaction_status (such as SUCCESS, UNCLAIMED, PENDING or RETURNED), amount, fee, receiver and any errors.Read-onlyGet Payout Item
Get one payout item by id, including transaction_status (such as SUCCESS, UNCLAIMED, PENDING or RETURNED), amount, fee, receiver and any errors. Returns the payout item object. Use payout_item_get to check a single recipient's payment, including denied items with no transaction_id. Use payout_get for the whole batch.
Inputs
payout_item_idstringrequired- The payout_item_id of one payout item, from payout_get. Example: 8AELMXH8UB2P8
paypal_plan_getGet one subscription billing plan by id, including status, billing cycles with prices, payment preferences and taxes.Read-onlyGet Plan
Get one subscription billing plan by id, including status, billing cycles with prices, payment preferences and taxes. Returns the plan object. Use plan_get to read a plan's pricing before subscription_create or plan_pricing_update. Use plans_list to find plan ids.
Inputs
plan_idstringrequired- The billing plan ID (starts with P-), returned by plan_create or plans_list. Example: P-5ML4271244454362WXNWU5NQ
paypal_plans_listList subscription billing plans in the PayPal account, optionally only those for one product, one page at a time.Read-onlyList Plans
List subscription billing plans in the PayPal account, optionally only those for one product, one page at a time. Returns plans with id, product_id, name, status and description, plus paging links. Use plans_list to find a plan_id for subscription_create. Use plan_get for a plan's billing cycles and prices.
Inputs
pageinteger- Page number to return, starting at 1. Defaults to 1. Combine with page_size: page=2 with page_size=20 returns items 21 to 40.
page_sizeinteger- Number of items per page, from 1 to 20. PayPal uses 10 when omitted.
product_idstring- Only plans for this catalog product. Example: PROD-XXCD1234QWER65782
total_requiredboolean- Set to true to include total_items and total_pages in the response so you know how many pages exist. Defaults to false.
paypal_product_getGet one catalog product by id, including name, description, type, category, image_url, home_url and timestamps.Read-onlyGet Product
Get one catalog product by id, including name, description, type, category, image_url, home_url and timestamps. Returns the product object. Use product_get for a known product. Use products_list to find product ids.
Inputs
product_idstringrequired- The catalog product ID, returned by product_create or products_list. System-generated IDs start with PROD-. Example: PROD-XXCD1234QWER65782
paypal_products_listList catalog products in the PayPal account one page at a time.Read-onlyList Products
List catalog products in the PayPal account one page at a time. Returns products with id, name, description and create_time, plus paging links. Use products_list to find a product_id for plan_create. Use product_get for one product's full details.
Inputs
pageinteger- Page number to return, starting at 1. Defaults to 1. Combine with page_size: page=2 with page_size=20 returns items 21 to 40.
page_sizeinteger- Number of items per page, from 1 to 20. PayPal uses 10 when omitted.
total_requiredboolean- Set to true to include total_items and total_pages in the response so you know how many pages exist. Defaults to false.
paypal_refund_getGet one PayPal refund by id, including status, amount, note_to_payer and seller_payable_breakdown.Read-onlyGet Refund
Get one PayPal refund by id, including status, amount, note_to_payer and seller_payable_breakdown. Returns the refund object. Use refund_get to check whether a refund from capture_refund has COMPLETED. Use capture_get for the original payment.
Inputs
refund_idstringrequired- The PayPal refund ID returned by capture_refund. Example: 1JU08902781691411
paypal_subscription_getGet one subscription by id, including status (APPROVAL_PENDING, APPROVED, ACTIVE, SUSPENDED, CANCELLED or EXPIRED), plan_id, subscriber, start_time and billing_info with the next billing time and last payment.Read-onlyGet Subscription
Get one subscription by id, including status (APPROVAL_PENDING, APPROVED, ACTIVE, SUSPENDED, CANCELLED or EXPIRED), plan_id, subscriber, start_time and billing_info with the next billing time and last payment. Returns the subscription object. Use subscription_get to check a subscriber's state. Use subscription_transactions_list for its payment history.
Inputs
subscription_idstringrequired- The subscription ID (starts with I-), returned by subscription_create. Example: I-BW452GLLEP1G
fieldsstring- Extra fields to include, comma-separated: last_failed_payment and/or plan (which embeds the full plan). Example: last_failed_payment,plan
paypal_subscription_transactions_listList the payment transactions of a subscription between two dates.Read-onlyList Subscription Transactions
List the payment transactions of a subscription between two dates. Returns transactions with id, status, amount_with_breakdown (gross, fee and net), payer name and email, and time. Use subscription_transactions_list for one subscription's billing history. Use transactions_list for all account activity.
Inputs
end_timestringrequired- End of the range, as an ISO 8601 date-time with seconds. Example: 2026-10-14T23:59:59Z
start_timestringrequired- Start of the range, as an ISO 8601 date-time with seconds. Example: 2026-01-01T00:00:00Z
subscription_idstringrequired- The subscription ID (starts with I-), returned by subscription_create. Example: I-BW452GLLEP1G
paypal_tracker_getGet one shipment tracker for a PayPal transaction by tracker id.Read-onlyGet Tracker
Get one shipment tracker for a PayPal transaction by tracker id. Returns the tracker with transaction_id, tracking_number, status, carrier, shipment_date and notify_buyer. Use tracker_get for a known tracker. Use trackers_list to find trackers by transaction.
Inputs
tracker_idstringrequired- The tracker ID, which is the PayPal transaction ID and tracking number joined by a hyphen. Example: 8MC585209K746392H-443844607820
paypal_trackers_listList shipment tracking records for a PayPal transaction, optionally narrowed to one tracking number.Read-onlyList Trackers
List shipment tracking records for a PayPal transaction, optionally narrowed to one tracking number. Returns trackers with transaction_id, tracking_number, status, carrier and shipment date. Use trackers_list to see tracking attached to a transaction. Use order_get to see trackers added to an order with order_tracking_add.
Inputs
transaction_idstringrequired- The PayPal transaction ID (capture ID) whose tracking to list. Example: 8MC585209K746392H
tracking_numberstring- Only the tracker with this tracking number. Example: 443844607820
paypal_transactions_listSearch the PayPal account's transaction history between two dates (at most 31 days apart, within the last three years), optionally filtered by transaction id, event code, status, amount or currency.Read-onlyList Transactions
Search the PayPal account's transaction history between two dates (at most 31 days apart, within the last three years), optionally filtered by transaction id, event code, status, amount or currency. Returns transaction_details with transaction_info (id, event code, status, amounts, fees, dates) and, if requested, payer, cart and shipping info, plus paging fields. Use transactions_list for account activity and reconciliation. Use balances_list for current balances. New transactions can take up to three hours to appear.
Inputs
end_datestringrequired- End of the range, at most 31 days after start_date. Example: 2026-10-14T23:59:59Z
start_datestringrequired- Start of the range, as an ISO 8601 date-time with seconds and a time zone. Example: 2026-10-01T00:00:00Z
balance_affecting_records_onlystring- Y (the default) returns only transactions that change the balance; N returns all transactions.one of
YN fieldsstring- Which sections to return, comma-separated: transaction_info (the default), payer_info, shipping_info, auction_info, cart_info, incentive_info, store_info, or all. Example: transaction_info,payer_info
pageinteger- Page number to return, starting at 1. Defaults to 1. Combine with page_size: page=2 with page_size=20 returns items 21 to 40.
page_sizeinteger- Number of items per page, from 1 to 500. PayPal uses 100 when omitted.
payment_instrument_typestring- Only transactions paid with this instrument type: CREDITCARD or DEBITCARD.
store_idstring- Only transactions from this store ID. Example: store-1
terminal_idstring- Only transactions from this terminal ID. Example: terminal-1
transaction_amountstring- Only transactions whose gross amount falls in a range, written as '<low> TO <high>' in the currency's smallest unit (cents for USD). PayPal's example for 5.00 to 10.05 is [500 TO 1005].
transaction_currencystring- Only transactions in this three-letter currency. Example: USD
transaction_idstring- Only the transaction with this PayPal transaction ID (17 characters). Example: 5TY05013RG002845M
transaction_statusstring- Only transactions in this status: D (denied), P (pending), S (successful) or V (reversed).one of
DPSV transaction_typestring- Only transactions with this PayPal event code, for example T0006 (express checkout payment) or T1107 (payment refund). Example: T0006
paypal_capture_refundRefund all or part of a captured PayPal payment to the buyer.WriteRefund Capture
Refund all or part of a captured PayPal payment to the buyer. Returns the refund with its id, status and amount. Use capture_refund with no amount for a full refund, or set amount_value and currency_code for a partial refund. Requires a capture id from order_capture, authorization_capture or order_get.
Inputs
capture_idstringrequired- The PayPal capture ID, found in purchase_units[].payments.captures[].id of the order returned by order_capture or order_get, or returned by authorization_capture. Example: 2GG279541U471931P
amount_valuestring- Amount to refund. Leave empty for a full refund as a decimal string in the currency's units, for example 10.50 for ten dollars and fifty cents. Use whole numbers for currencies without decimals such as JPY. Set currency_code together with this field.
currency_codestring- Three-letter ISO 4217 currency code for the refund amount, in upper case. Required whenever an amount is given. Example: USD
custom_idstring- Your own reference for reconciling this refund in PayPal reports, up to 127 characters. Example: refund-7781
invoice_idstring- Your own invoice number for this refund, up to 127 characters. Example: INV-1001-R
note_to_payerstring- The reason for the refund, shown to the buyer in their transaction history and email. Up to 255 characters. Example: Item returned
request_idstring- Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a
paypal_dispute_escalateEscalate a dispute in the INQUIRY stage to a PayPal claim so PayPal reviews and decides it.WriteEscalate Dispute
Escalate a dispute in the INQUIRY stage to a PayPal claim so PayPal reviews and decides it. Returns links to the updated dispute. Use dispute_escalate when you cannot settle with the buyer directly. Use dispute_offer_make to propose a settlement first.
Inputs
dispute_idstringrequired- The PayPal dispute ID (starts with PP-), returned by disputes_list. Example: PP-D-27803
notestring- Your note about why the dispute is being escalated, 1 to 2000 characters. Example: Buyer did not respond to our refund offer.
paypal_dispute_offer_makeOffer the buyer a resolution for a dispute in the INQUIRY stage: a refund, a refund after return, a refund with replacement, or a replacement without refund.WriteMake Dispute Offer
Offer the buyer a resolution for a dispute in the INQUIRY stage: a refund, a refund after return, a refund with replacement, or a replacement without refund. Returns links to the updated dispute; if the buyer accepts, PayPal refunds automatically. Use dispute_offer_make to propose a settlement. Check allowed offer types under allowed_response_options in dispute_get first.
Inputs
dispute_idstringrequired- The PayPal dispute ID (starts with PP-), returned by disputes_list. Example: PP-D-27803
notestringrequired- Your note to the buyer about the offer, 1 to 2000 characters. Example: We can refund 20 USD to resolve this.
offer_typestringrequired- REFUND, REFUND_WITH_RETURN, REFUND_WITH_REPLACEMENT or REPLACEMENT_WITHOUT_REFUND.one of
REFUNDREFUND_WITH_RETURNREFUND_WITH_REPLACEMENTREPLACEMENT_WITHOUT_REFUND currency_codestring- Three-letter ISO 4217 currency code for the offered amount, in upper case. Required whenever an amount is given. Example: USD
invoice_idstring- Your invoice ID for the refund, to match it in your own records. Example: INV-1001-R
offer_amount_valuestring- Amount offered to the buyer as a decimal string in the currency's units, for example 10.50 for ten dollars and fifty cents. Use whole numbers for currencies without decimals such as JPY. Set currency_code together with this field.
return_shipping_addressobject- Where the buyer should send the item back, for REFUND_WITH_RETURN offers: address_line_1, admin_area_2 (city), admin_area_1 (state), postal_code and country_code. Example: {"address_line_1": "2211 N First Street", "admin_area_2": "San Jose", "admin_area_1": "CA", "postal_code": "95131", "country_code": "US"}
paypal_invoice_cancelCancel a sent PayPal invoice so it can no longer be paid, and optionally notify the recipient, the merchant and CC addresses.WriteCancel Invoice
Cancel a sent PayPal invoice so it can no longer be paid, and optionally notify the recipient, the merchant and CC addresses. Returns an empty success (HTTP 204). Use invoice_cancel for sent, unpaid invoices. Draft invoices are deleted rather than cancelled, which this connector does not do.
Inputs
invoice_idstringrequired- The PayPal invoice ID (starts with INV2-), returned by invoice_create, invoices_list or invoices_search. Example: INV2-Z56S-5LLA-Q52L-CPZ5
additional_recipientsarray- Email addresses to CC on the notification. If omitted, PayPal notifies every CC address already on the invoice. Example: ["accounts@example.com"]
send_to_invoicerboolean- Whether PayPal also emails a copy to the merchant (invoicer). Defaults to false.
send_to_recipientboolean- Whether PayPal emails the invoice recipient. Defaults to true. Set to false to skip the email, for example when you share the invoice link yourself.
paypal_invoice_createCreate a draft PayPal invoice with its currency, invoice details, recipients and line items.WriteCreate Invoice
Create a draft PayPal invoice with its currency, invoice details, recipients and line items. Returns the new invoice, including its id and status DRAFT. Use invoice_create to draft an invoice, then invoice_send to deliver it. Use invoice_number_generate first if you want to set the invoice number yourself.
Inputs
detailobjectrequired- Invoice details. currency_code (three-letter code) is required. You can also set invoice_number (auto-incremented when omitted), reference such as a PO number, invoice_date (YYYY-MM-DD), payment_term with term_type (DUE_ON_RECEIPT, NET_10, NET_15, NET_30, NET_45, NET_60, NET_90, NO_DUE_DATE or DUE_ON_DATE_SPECIFIED with a due_date), a note shown to the recipient, terms_and_conditions and a private memo. Example: {"currency_code": "USD", "invoice_number": "INV-1001", "invoice_date": "2026-10-14", "payment_term": {"term_type": "NET_30"}, "note": "Thank you for your business."}
additional_recipientsarray- Email addresses to CC on invoice notifications. Example: ["accounts@example.com"]
amountobject- Invoice-level amount adjustments in a breakdown object: shipping (amount and optional tax), discount (invoice_discount as percent or amount) and custom (label and amount). PayPal calculates item and tax totals itself. Example: {"breakdown": {"shipping": {"amount": {"currency_code": "USD", "value": "10.00"}}}}
configurationobject- Invoice options: allow_tip, tax_calculated_after_discount, tax_inclusive, partial_payment (allow_partial_payment and minimum_amount_due) and template_id. Example: {"allow_tip": false, "partial_payment": {"allow_partial_payment": true, "minimum_amount_due": {"currency_code": "USD", "value": "50.00"}}}
invoicerobject- The merchant's business details printed on the invoice: business_name, a name object, an address object, email_address, phones, website, tax_id, additional_notes and logo_url. When omitted, PayPal uses the account's profile. Example: {"business_name": "Acme Supplies", "email_address": "billing@acme.example", "website": "https://acme.example"}
itemsarray- Line items. Each item needs a name, a quantity (string, up to five decimals) and a unit_amount with currency_code and value; you can add description, tax (name and percent), discount (percent or amount), item_date and unit_of_measure (QUANTITY, HOURS or AMOUNT). Example: [{"name": "Consulting", "quantity": "2", "unit_amount": {"currency_code": "USD", "value": "150.00"}, "unit_of_measure": "HOURS"}]
primary_recipientsarray- Who the invoice is billed to. Each entry has a billing_info object (email_address, name with given_name and surname, business_name, address, phones, language) and an optional shipping_info object. Example: [{"billing_info": {"email_address": "customer@example.com", "name": {"given_name": "Jane", "surname": "Doe"}}}]
paypal_invoice_number_generateGenerate the next available invoice number for the PayPal account by incrementing the last one used (INVOICE-1234 becomes INVOICE-1235).WriteGenerate Invoice Number
Generate the next available invoice number for the PayPal account by incrementing the last one used (INVOICE-1234 becomes INVOICE-1235). Returns invoice_number. Use invoice_number_generate before invoice_create when you want to set detail.invoice_number yourself; otherwise invoice_create assigns the next number automatically.
Inputs
This tool takes no inputs.
paypal_invoice_payment_recordRecord a payment received outside PayPal (cash, check, bank transfer and so on) against a sent PayPal invoice.WriteRecord Invoice Payment
Record a payment received outside PayPal (cash, check, bank transfer and so on) against a sent PayPal invoice. Returns the payment_id of the recorded payment; the invoice becomes PAID when nothing is left due, otherwise PARTIALLY_PAID. Use invoice_payment_record for off-PayPal payments; payments made through PayPal are recorded automatically.
Inputs
invoice_idstringrequired- The PayPal invoice ID (starts with INV2-), returned by invoice_create, invoices_list or invoices_search. Example: INV2-Z56S-5LLA-Q52L-CPZ5
methodstringrequired- How the payment was made: BANK_TRANSFER, CASH, CHECK, CREDIT_CARD, DEBIT_CARD, PAYPAL, WIRE_TRANSFER or OTHER.one of
BANK_TRANSFERCASHCHECKCREDIT_CARDDEBIT_CARDPAYPALWIRE_TRANSFEROTHER amount_valuestring- Amount received. Leave empty to record the full amount due as a decimal string in the currency's units, for example 10.50 for ten dollars and fifty cents. Use whole numbers for currencies without decimals such as JPY. Set currency_code together with this field.
currency_codestring- Three-letter ISO 4217 currency code for the payment amount, in upper case. Required whenever an amount is given. Example: USD
notestring- A note about the payment, such as a check number, up to 2000 characters. Example: Check #2041
payment_datestring- Date the payment was received, as YYYY-MM-DD. Example: 2026-10-14
paypal_invoice_qr_code_generateGenerate a QR code image for a sent PayPal invoice, which buyers scan to view or pay it on their phone.WriteGenerate Invoice QR Code
Generate a QR code image for a sent PayPal invoice, which buyers scan to view or pay it on their phone. Returns the QR code as a Base64-encoded PNG image. Use invoice_qr_code_generate to add a pay code to a printed or PDF invoice; the invoice must have been sent with invoice_send first.
Inputs
invoice_idstringrequired- The PayPal invoice ID (starts with INV2-), returned by invoice_create, invoices_list or invoices_search. Example: INV2-Z56S-5LLA-Q52L-CPZ5
actionstring- What the QR code opens: pay (the payment page, the default) or details (the invoice details page).one of
paydetails heightinteger- Image height in pixels, from 150 to 500. PayPal uses 500 when omitted.
widthinteger- Image width in pixels, from 150 to 500. PayPal uses 500 when omitted.
paypal_invoice_refund_recordRecord a refund made outside PayPal against a paid PayPal invoice.WriteRecord Invoice Refund
Record a refund made outside PayPal against a paid PayPal invoice. Returns the refund_id of the recorded refund; the invoice becomes REFUNDED when all payments are refunded, otherwise PARTIALLY_REFUNDED. Use invoice_refund_record for refunds of payments recorded with invoice_payment_record. Use capture_refund to send money back for a PayPal payment.
Inputs
invoice_idstringrequired- The PayPal invoice ID (starts with INV2-), returned by invoice_create, invoices_list or invoices_search. Example: INV2-Z56S-5LLA-Q52L-CPZ5
methodstringrequired- How the refund was made: BANK_TRANSFER, CASH, CHECK, CREDIT_CARD, DEBIT_CARD, PAYPAL, WIRE_TRANSFER or OTHER.one of
BANK_TRANSFERCASHCHECKCREDIT_CARDDEBIT_CARDPAYPALWIRE_TRANSFEROTHER amount_valuestring- Amount refunded. Leave empty to record a refund of the full amount paid as a decimal string in the currency's units, for example 10.50 for ten dollars and fifty cents. Use whole numbers for currencies without decimals such as JPY. Set currency_code together with this field.
currency_codestring- Three-letter ISO 4217 currency code for the refund amount, in upper case. Required whenever an amount is given. Example: USD
refund_datestring- Date the refund was made, as YYYY-MM-DD. Example: 2026-10-14
paypal_invoice_remindEmail a payment reminder for a PayPal invoice that was sent and is not yet paid.WriteSend Invoice Reminder
Email a payment reminder for a PayPal invoice that was sent and is not yet paid. Returns an empty success (HTTP 204). Use invoice_remind for invoices already delivered with invoice_send; PayPal allows two reminders per day. Use invoice_send for a draft that has never been sent.
Inputs
invoice_idstringrequired- The PayPal invoice ID (starts with INV2-), returned by invoice_create, invoices_list or invoices_search. Example: INV2-Z56S-5LLA-Q52L-CPZ5
additional_recipientsarray- Email addresses to CC on the notification. If omitted, PayPal notifies every CC address already on the invoice. Example: ["accounts@example.com"]
send_to_invoicerboolean- Whether PayPal also emails a copy to the merchant (invoicer). Defaults to false.
send_to_recipientboolean- Whether PayPal emails the invoice recipient. Defaults to true. Set to false to skip the email, for example when you share the invoice link yourself.
paypal_invoice_sendSend a draft PayPal invoice to its recipients, or schedule it when the invoice date is in the future.WriteSend Invoice
Send a draft PayPal invoice to its recipients, or schedule it when the invoice date is in the future. Returns a link to the payer's view of the invoice. Use invoice_send after invoice_create. Use invoice_remind for an invoice that was already sent.
Inputs
invoice_idstringrequired- The PayPal invoice ID (starts with INV2-), returned by invoice_create, invoices_list or invoices_search. Example: INV2-Z56S-5LLA-Q52L-CPZ5
additional_recipientsarray- Email addresses to CC on the notification. If omitted, PayPal notifies every CC address already on the invoice. Example: ["accounts@example.com"]
send_to_invoicerboolean- Whether PayPal also emails a copy to the merchant (invoicer). Defaults to false.
send_to_recipientboolean- Whether PayPal emails the invoice recipient. Defaults to true. Set to false to skip the email, for example when you share the invoice link yourself.
paypal_invoice_template_createCreate a reusable PayPal invoice template with prefilled invoice details, items and display settings; an account can hold up to 50 templates.WriteCreate Invoice Template
Create a reusable PayPal invoice template with prefilled invoice details, items and display settings; an account can hold up to 50 templates. Returns the new template with its id. Use invoice_template_create to save a standard invoice layout. Use invoice_create to make an actual invoice.
Inputs
namestringrequired- Template name, unique within the account, 1 to 500 characters. Example: Hourly consulting
default_templateboolean- Set to true to make this the account's default invoice template. An account has one default template.
settingsobject- Which fields the template shows or hides. template_item_settings is a list of {field_name, display_preference: {hidden}} entries for item fields (items.date, items.discount, items.tax, items.description, items.quantity) and template_subtotal_settings does the same for subtotal fields (discount, shipping, custom). Example: {"template_item_settings": [{"field_name": "items.date", "display_preference": {"hidden": true}}]}
template_infoobject- Prefilled invoice content: detail (currency_code, note, terms_and_conditions, payment_term), invoicer, primary_recipients, additional_recipients, items, configuration and amount, shaped as in invoice_create. Example: {"detail": {"currency_code": "USD", "payment_term": {"term_type": "NET_30"}}, "items": [{"name": "Consulting", "quantity": "1", "unit_amount": {"currency_code": "USD", "value": "150.00"}}]}
unit_of_measurestring- How line items are billed: QUANTITY (units), HOURS (time) or AMOUNT (a flat amount).one of
QUANTITYHOURSAMOUNT
paypal_invoice_template_updateReplace a PayPal invoice template with a complete new version; fields you leave out are cleared.WriteUpdate Invoice Template
Replace a PayPal invoice template with a complete new version; fields you leave out are cleared. Returns the updated template. Use invoice_template_update after reading the current template with invoice_template_get and resending every field you want to keep.
- Idempotent
Inputs
namestringrequired- Template name, unique within the account, 1 to 500 characters. Example: Hourly consulting
template_idstringrequired- The invoice template ID (starts with TEMP-), returned by invoice_templates_list or invoice_template_create. Example: TEMP-19V05281TU309413B
default_templateboolean- Set to true to make this the account's default invoice template. An account has one default template.
settingsobject- Which fields the template shows or hides. template_item_settings is a list of {field_name, display_preference: {hidden}} entries for item fields (items.date, items.discount, items.tax, items.description, items.quantity) and template_subtotal_settings does the same for subtotal fields (discount, shipping, custom). Example: {"template_item_settings": [{"field_name": "items.date", "display_preference": {"hidden": true}}]}
template_infoobject- Prefilled invoice content: detail (currency_code, note, terms_and_conditions, payment_term), invoicer, primary_recipients, additional_recipients, items, configuration and amount, shaped as in invoice_create. Example: {"detail": {"currency_code": "USD", "payment_term": {"term_type": "NET_30"}}, "items": [{"name": "Consulting", "quantity": "1", "unit_amount": {"currency_code": "USD", "value": "150.00"}}]}
unit_of_measurestring- How line items are billed: QUANTITY (units), HOURS (time) or AMOUNT (a flat amount).one of
QUANTITYHOURSAMOUNT
paypal_invoice_updateReplace a PayPal invoice with a complete new version; fields you leave out are cleared, so send the whole invoice.WriteUpdate Invoice
Replace a PayPal invoice with a complete new version; fields you leave out are cleared, so send the whole invoice. Returns the updated invoice. Use invoice_update after reading the current invoice with invoice_get, and resend changed fields along with unchanged ones. PayPal allows changing the recipient only twice in 72 hours.
- Idempotent
Inputs
detailobjectrequired- Invoice details. currency_code (three-letter code) is required. You can also set invoice_number (auto-incremented when omitted), reference such as a PO number, invoice_date (YYYY-MM-DD), payment_term with term_type (DUE_ON_RECEIPT, NET_10, NET_15, NET_30, NET_45, NET_60, NET_90, NO_DUE_DATE or DUE_ON_DATE_SPECIFIED with a due_date), a note shown to the recipient, terms_and_conditions and a private memo. Example: {"currency_code": "USD", "invoice_number": "INV-1001", "invoice_date": "2026-10-14", "payment_term": {"term_type": "NET_30"}, "note": "Thank you for your business."}
invoice_idstringrequired- The PayPal invoice ID (starts with INV2-), returned by invoice_create, invoices_list or invoices_search. Example: INV2-Z56S-5LLA-Q52L-CPZ5
additional_recipientsarray- Email addresses to CC on invoice notifications. Example: ["accounts@example.com"]
amountobject- Invoice-level amount adjustments in a breakdown object: shipping (amount and optional tax), discount (invoice_discount as percent or amount) and custom (label and amount). PayPal calculates item and tax totals itself. Example: {"breakdown": {"shipping": {"amount": {"currency_code": "USD", "value": "10.00"}}}}
configurationobject- Invoice options: allow_tip, tax_calculated_after_discount, tax_inclusive, partial_payment (allow_partial_payment and minimum_amount_due) and template_id. Example: {"allow_tip": false, "partial_payment": {"allow_partial_payment": true, "minimum_amount_due": {"currency_code": "USD", "value": "50.00"}}}
invoicerobject- The merchant's business details printed on the invoice: business_name, a name object, an address object, email_address, phones, website, tax_id, additional_notes and logo_url. When omitted, PayPal uses the account's profile. Example: {"business_name": "Acme Supplies", "email_address": "billing@acme.example", "website": "https://acme.example"}
itemsarray- Line items. Each item needs a name, a quantity (string, up to five decimals) and a unit_amount with currency_code and value; you can add description, tax (name and percent), discount (percent or amount), item_date and unit_of_measure (QUANTITY, HOURS or AMOUNT). Example: [{"name": "Consulting", "quantity": "2", "unit_amount": {"currency_code": "USD", "value": "150.00"}, "unit_of_measure": "HOURS"}]
primary_recipientsarray- Who the invoice is billed to. Each entry has a billing_info object (email_address, name with given_name and surname, business_name, address, phones, language) and an optional shipping_info object. Example: [{"billing_info": {"email_address": "customer@example.com", "name": {"given_name": "Jane", "surname": "Doe"}}}]
send_to_invoicerboolean- Whether PayPal emails the merchant about the update. Defaults to true.
send_to_recipientboolean- Whether PayPal emails the recipient about the update. Defaults to true.
paypal_invoices_searchSearch PayPal invoices by recipient email or name, invoice number, status, currency, total amount range or date range; an invoice must match every criterion you give.WriteSearch Invoices
Search PayPal invoices by recipient email or name, invoice number, status, currency, total amount range or date range; an invoice must match every criterion you give. Returns matching invoices with id, status, detail, recipients and amount, plus paging links. Use invoices_search to filter. Use invoices_list to browse everything.
Inputs
archivedboolean- true returns only archived invoices, false only unarchived ones. Leave empty to include both.
creation_date_rangeobject- Only invoices created within this range, given as start and end date-times (ISO 8601). Example: {"start": "2026-10-01T00:00:00Z", "end": "2026-10-31T23:59:59Z"}
currency_codestring- Only invoices in this three-letter currency. Example: USD
due_date_rangeobject- Only invoices whose due date falls in this range, given as start and end dates (YYYY-MM-DD). Example: {"start": "2026-10-01", "end": "2026-10-31"}
invoice_date_rangeobject- Only invoices whose invoice date falls in this range, given as start and end dates (YYYY-MM-DD). Example: {"start": "2026-01-01", "end": "2026-03-31"}
invoice_numberstring- Only the invoice with this invoice number. Example: INV-1001
memostring- Only invoices whose private memo matches this text. Example: Q4 retainer
pageinteger- Page number to return, starting at 1. Defaults to 1. Combine with page_size: page=2 with page_size=20 returns items 21 to 40.
page_sizeinteger- Number of items per page, from 1 to 100. PayPal uses 20 when omitted.
payment_date_rangeobject- Only invoices paid within this range, given as start and end date-times (ISO 8601). Example: {"start": "2026-10-01T00:00:00Z", "end": "2026-10-31T23:59:59Z"}
recipient_business_namestring- Only invoices whose recipient has this business name. Example: Globex Corp
recipient_emailstring- Only invoices billed to this email address. Example: customer@example.com
recipient_first_namestring- Only invoices whose recipient has this first name. Example: Jane
recipient_last_namestring- Only invoices whose recipient has this last name. Example: Doe
referencestring- Only invoices with this reference, such as a purchase order number. Example: PO-5521
statusarray- Only invoices in any of these statuses: DRAFT, SENT, SCHEDULED, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_PAID, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED, UNPAID or PAYMENT_PENDING. Example: ["SENT", "UNPAID"]
total_amount_rangeobject- Only invoices whose total falls in this range, given as lower_amount and upper_amount, each with currency_code and value. Example: {"lower_amount": {"currency_code": "USD", "value": "100.00"}, "upper_amount": {"currency_code": "USD", "value": "500.00"}}
total_requiredboolean- Set to true to include total_items and total_pages in the response so you know how many pages exist. Defaults to false.
paypal_order_captureCapture payment for a PayPal order created with intent CAPTURE, moving the funds to the merchant.WriteCapture Order
Capture payment for a PayPal order created with intent CAPTURE, moving the funds to the merchant. Returns the order with status COMPLETED and purchase_units[].payments.captures, whose id you need for capture_refund. Use order_capture for intent CAPTURE orders. Use authorization_capture for a payment held with order_authorize. The buyer must approve the order first unless you pass a payment_source.
Inputs
order_idstringrequired- The PayPal order ID returned by order_create (also shown in the buyer's approval URL as the token parameter). Example: 5O190127TN364715T
payment_sourceobject- Optional payment source to charge without a separate buyer approval, such as a saved PayPal wallet or card by vault_id. Leave empty for the normal flow where the buyer has already approved the order. Example: {"paypal": {"vault_id": "8kk8451t"}}
request_idstring- Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a
paypal_order_createCreate a PayPal checkout order for one or more purchase units, with intent CAPTURE (take the payment once the buyer approves) or AUTHORIZE (hold the funds and capture later).WriteCreate Order
Create a PayPal checkout order for one or more purchase units, with intent CAPTURE (take the payment once the buyer approves) or AUTHORIZE (hold the funds and capture later). Returns the order id, status (usually CREATED, or PAYER_ACTION_REQUIRED) and links, including the approve link the buyer must open. Use order_create to start a payment, then order_capture or order_authorize after approval. Use invoice_create to bill a customer by email instead.
Inputs
intentstringrequired- CAPTURE takes the payment as soon as the buyer approves and you call order_capture. AUTHORIZE places a hold that you capture later with authorization_capture (after order_authorize).one of
CAPTUREAUTHORIZE purchase_unitsarrayrequired- One or more purchase units (up to 10). Each needs an amount with a three-letter currency_code and a string value. Add a reference_id when there is more than one unit, and optionally description, custom_id, invoice_id, soft_descriptor, items (with name, quantity and unit_amount, which then requires amount.breakdown.item_total) and shipping. Example: [{"reference_id": "default", "description": "Order #1001", "amount": {"currency_code": "USD", "value": "25.00"}}]
payment_sourceobject- Optional payment source. For PayPal checkout, pass a paypal object with experience_context to set return_url and cancel_url (where the buyer lands after approving or cancelling), brand_name, user_action (PAY_NOW or CONTINUE) and shipping_preference. You can also charge a saved instrument with vault_id. Example: {"paypal": {"experience_context": {"return_url": "https://example.com/return", "cancel_url": "https://example.com/cancel", "user_action": "PAY_NOW"}}}
request_idstring- Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a
paypal_order_tracker_updateUpdate or cancel a shipment tracker on a PayPal order using JSON Patch operations: replace the items, add or replace notify_payer, or replace status with CANCELLED.WriteUpdate Order Tracker
Update or cancel a shipment tracker on a PayPal order using JSON Patch operations: replace the items, add or replace notify_payer, or replace status with CANCELLED. Returns no body on success (HTTP 204). Use order_tracker_update for trackers added with order_tracking_add. Use tracker_update for trackers on the older transaction-level tracking API.
Inputs
order_idstringrequired- The PayPal order ID returned by order_create (also shown in the buyer's approval URL as the token parameter). Example: 5O190127TN364715T
patch_operationsarrayrequired- JSON Patch (RFC 6902) operations to apply. Each operation has an op (add, replace or remove), a path that is a JSON Pointer to the field, and, for add and replace, the new value. Supported: replace /items, add or replace /notify_payer, replace /status with CANCELLED. Example: [{"op": "replace", "path": "/status", "value": "CANCELLED"}]
tracker_idstringrequired- The order tracker ID from purchase_units[].shipping.trackers[].id in order_get or order_tracking_add. Example: 8MC585209K746392H
paypal_order_tracking_addAdd shipment tracking (carrier and tracking number) to a captured PayPal order, optionally emailing the buyer.WriteAdd Order Tracking
Add shipment tracking (carrier and tracking number) to a captured PayPal order, optionally emailing the buyer. Returns the updated order, including purchase_units[].shipping.trackers with the new tracker id. Use order_tracking_add for orders paid through the Orders API. Use order_tracker_update to change or cancel that tracker. Requires the capture id from order_capture or order_get.
Inputs
capture_idstringrequired- The PayPal capture ID, found in purchase_units[].payments.captures[].id of the order returned by order_capture or order_get, or returned by authorization_capture. Example: 2GG279541U471931P
carrierstringrequired- PayPal carrier code in upper case, for example USPS, UPS, FEDEX, DHL or DHL_API; regional carriers use codes such as ROYAL_MAIL or CA_CANADA_POST. Use OTHER together with carrier_name_other when the carrier is not listed. Example: USPS
order_idstringrequired- The PayPal order ID returned by order_create (also shown in the buyer's approval URL as the token parameter). Example: 5O190127TN364715T
tracking_numberstringrequired- The carrier's tracking number for the shipment, 1 to 64 characters. Example: 92001902416702000000000033
carrier_name_otherstring- Carrier name to show when carrier is OTHER. Example: Local Courier Co
itemsarray- Optional list of the items in this shipment, each with name, quantity and optionally sku, url, image_url and upc. Example: [{"name": "T-shirt", "quantity": "1", "sku": "TS-001"}]
notify_payerboolean- Set to true to email the buyer the tracking details. Defaults to false.
paypal_order_updateUpdate a PayPal order that is still CREATED or APPROVED using JSON Patch operations, for example to change a purchase unit's amount, description, invoice_id, custom_id or shipping address.WriteUpdate Order
Update a PayPal order that is still CREATED or APPROVED using JSON Patch operations, for example to change a purchase unit's amount, description, invoice_id, custom_id or shipping address. Returns no body on success (HTTP 204); call order_get to read the updated order. Use order_update before capturing or authorizing; a COMPLETED order cannot be changed.
Inputs
order_idstringrequired- The PayPal order ID returned by order_create (also shown in the buyer's approval URL as the token parameter). Example: 5O190127TN364715T
patch_operationsarrayrequired- JSON Patch (RFC 6902) operations to apply. Each operation has an op (add, replace or remove), a path that is a JSON Pointer to the field, and, for add and replace, the new value. Paths address a purchase unit by reference_id, for example /purchase_units/@reference_id=='default'/description. Example: [{"op": "replace", "path": "/purchase_units/@reference_id=='default'/amount", "value": {"currency_code": "USD", "value": "30.00"}}]
paypal_payout_createSend money to one or more recipients, identified by email, phone, PayPal payer ID or Venmo handle, in one batch payout.WriteCreate Payout
Send money to one or more recipients, identified by email, phone, PayPal payer ID or Venmo handle, in one batch payout. Returns the batch_header with payout_batch_id and batch_status (usually PENDING). Use payout_create to pay people out, then payout_get to follow each item's status. Requires Payouts to be enabled on the PayPal account; PayPal rejects a sender_batch_id reused within 30 days.
Inputs
itemsarrayrequired- Payout items, one per recipient. Each needs receiver (the email, phone, payer ID or handle) and amount (currency and value), and can set recipient_type, note, sender_item_id, recipient_wallet (PAYPAL or VENMO) and purpose. Example: [{"recipient_type": "EMAIL", "receiver": "recipient@example.com", "amount": {"currency": "USD", "value": "9.87"}, "note": "Thanks!", "sender_item_id": "item-1"}]
sender_batch_headerobjectrequired- Batch settings: sender_batch_id (your unique id for the batch, reused ids are rejected for 30 days), email_subject and email_message for the recipient email, recipient_type default (EMAIL, PHONE, PAYPAL_ID or USER_HANDLE) and a note. Example: {"sender_batch_id": "Payouts_2026_10_14_001", "email_subject": "You have a payout!", "email_message": "You received a payout. Thanks for using our service!"}
request_idstring- Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a
paypal_payout_item_cancelCancel an UNCLAIMED payout item so the funds return to the sender before PayPal's automatic 30-day return.WriteCancel Payout Item
Cancel an UNCLAIMED payout item so the funds return to the sender before PayPal's automatic 30-day return. Returns the payout item with transaction_status RETURNED. Use payout_item_cancel only for items whose status is UNCLAIMED. Use payout_item_get to check the status first.
Inputs
payout_item_idstringrequired- The payout_item_id of one payout item, from payout_get. Example: 8AELMXH8UB2P8
paypal_plan_activateActivate a billing plan so new subscriptions can be created on it.WriteActivate Plan
Activate a billing plan so new subscriptions can be created on it. Returns an empty success (HTTP 204). Use plan_activate for a plan created with status CREATED or deactivated earlier. Use plan_deactivate to stop new sign-ups.
Inputs
plan_idstringrequired- The billing plan ID (starts with P-), returned by plan_create or plans_list. Example: P-5ML4271244454362WXNWU5NQ
paypal_plan_createCreate a subscription billing plan for a catalog product, with up to two trial cycles plus one regular billing cycle, payment preferences and optional taxes.WriteCreate Plan
Create a subscription billing plan for a catalog product, with up to two trial cycles plus one regular billing cycle, payment preferences and optional taxes. Returns the plan with its id (P-...), status and billing cycles. Use plan_create before subscription_create, which needs a plan_id. Requires a product_id from product_create or products_list.
Inputs
billing_cyclesarrayrequired- Billing cycles run in sequence order. Each has a frequency (interval_unit DAY, WEEK, MONTH or YEAR and interval_count), tenure_type TRIAL or REGULAR, a sequence number starting at 1, total_cycles (0 means the regular cycle repeats until cancelled) and a pricing_scheme with fixed_price (currency_code and value); a free trial omits pricing_scheme. Example: [{"frequency": {"interval_unit": "MONTH", "interval_count": 1}, "tenure_type": "REGULAR", "sequence": 1, "total_cycles": 0, "pricing_scheme": {"fixed_price": {"currency_code": "USD", "value": "10.00"}}}]
namestringrequired- Plan name, 1 to 127 characters. Example: Basic Monthly
payment_preferencesobjectrequired- How payments are handled: auto_bill_outstanding (bill missed amounts in the next cycle, default true), setup_fee (currency_code and value charged at sign-up), setup_fee_failure_action (CONTINUE or CANCEL) and payment_failure_threshold (failed payments allowed before suspension). Example: {"auto_bill_outstanding": true, "setup_fee_failure_action": "CONTINUE", "payment_failure_threshold": 3}
product_idstringrequired- The catalog product this plan bills for, from product_create or products_list. Example: PROD-XXCD1234QWER65782
descriptionstring- Plan description, 1 to 127 characters. Example: Basic plan billed monthly
quantity_supportedboolean- Set to true to let subscribers choose a quantity of the product. Defaults to false.
request_idstring- Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a
statusstring- Initial plan status: ACTIVE (the default; subscriptions can be created right away) or CREATED (activate later with plan_activate).one of
CREATEDACTIVE taxesobject- Tax applied to the plan: percentage as a string and inclusive (true if the price already includes tax). Example: {"percentage": "10", "inclusive": false}
paypal_plan_deactivateDeactivate a billing plan so no new subscriptions can be created on it; existing subscriptions keep billing.WriteDeactivate Plan
Deactivate a billing plan so no new subscriptions can be created on it; existing subscriptions keep billing. Returns an empty success (HTTP 204). Use plan_deactivate to retire a plan. Use plan_activate to re-enable it.
Inputs
plan_idstringrequired- The billing plan ID (starts with P-), returned by plan_create or plans_list. Example: P-5ML4271244454362WXNWU5NQ
paypal_plan_pricing_updateChange the prices of one or more billing cycles in a plan, for example raising the regular cycle from 5 to 7 USD a month.WriteUpdate Plan Pricing
Change the prices of one or more billing cycles in a plan, for example raising the regular cycle from 5 to 7 USD a month. Returns an empty success (HTTP 204). Use plan_pricing_update to change prices. Use plan_update for other plan settings. Price changes apply to existing subscriptions according to PayPal's notice rules.
Inputs
plan_idstringrequired- The billing plan ID (starts with P-), returned by plan_create or plans_list. Example: P-5ML4271244454362WXNWU5NQ
pricing_schemesarrayrequired- New prices by billing cycle: each entry has billing_cycle_sequence (the cycle's sequence number from plan_get) and a pricing_scheme with fixed_price (currency_code and value). Example: [{"billing_cycle_sequence": 1, "pricing_scheme": {"fixed_price": {"currency_code": "USD", "value": "7.00"}}}]
paypal_plan_updateUpdate a CREATED or ACTIVE billing plan using JSON Patch operations, for example its description, tax percentage or payment preferences such as auto_bill_outstanding, payment_failure_threshold, setup_fee and setup_fee_failure_action.WriteUpdate Plan
Update a CREATED or ACTIVE billing plan using JSON Patch operations, for example its description, tax percentage or payment preferences such as auto_bill_outstanding, payment_failure_threshold, setup_fee and setup_fee_failure_action. Returns no body on success (HTTP 204). Use plan_update for those fields. Use plan_pricing_update to change prices and plan_activate or plan_deactivate to change status.
Inputs
patch_operationsarrayrequired- JSON Patch (RFC 6902) operations to apply. Each operation has an op (add, replace or remove), a path that is a JSON Pointer to the field, and, for add and replace, the new value. Patchable paths include /description, /taxes/percentage, /payment_preferences/auto_bill_outstanding, /payment_preferences/payment_failure_threshold, /payment_preferences/setup_fee and /payment_preferences/setup_fee_failure_action (replace). Example: [{"op": "replace", "path": "/payment_preferences/payment_failure_threshold", "value": 7}]
plan_idstringrequired- The billing plan ID (starts with P-), returned by plan_create or plans_list. Example: P-5ML4271244454362WXNWU5NQ
paypal_product_createCreate a catalog product (a physical good, digital good or service) for subscription plans to be built on.WriteCreate Product
Create a catalog product (a physical good, digital good or service) for subscription plans to be built on. Returns the product with its id (PROD-...), name, type and category. Use product_create before plan_create, which needs a product_id. Use products_list to reuse an existing product.
Inputs
namestringrequired- Product name, 1 to 127 characters. Example: Video Streaming Service
typestringrequired- PHYSICAL for physical goods, DIGITAL for digital goods or SERVICE for a service.one of
PHYSICALDIGITALSERVICE categorystring- PayPal product category code in upper case with underscores, for example SOFTWARE, DIGITAL_MEDIA_BOOKS_MOVIES_MUSIC, CLOTHING_ACCESSORIES_AND_SHOES or MEMBERSHIP_CLUBS_AND_ORGANIZATIONS. Example: SOFTWARE
descriptionstring- Product description, 1 to 256 characters. Example: Monthly access to HD video streaming
home_urlstring- URL of the product's home page. Example: https://example.com/home
idstring- Optional product ID or SKU, 6 to 50 characters. PayPal generates a PROD- id when omitted. Example: SKU-VIDEO-001
image_urlstring- URL of the product image. Example: https://example.com/streaming.jpg
request_idstring- Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a
paypal_product_updateUpdate a catalog product's description, category, image_url or home_url using JSON Patch operations.WriteUpdate Product
Update a catalog product's description, category, image_url or home_url using JSON Patch operations. Returns no body on success (HTTP 204); call product_get to read the result. Use product_update for those four fields; a product's name and type cannot be changed.
Inputs
patch_operationsarrayrequired- JSON Patch (RFC 6902) operations to apply. Each operation has an op (add, replace or remove), a path that is a JSON Pointer to the field, and, for add and replace, the new value. Patchable paths: /description, /category, /image_url and /home_url (add, replace or remove). Example: [{"op": "replace", "path": "/description", "value": "Premium video streaming service"}]
product_idstringrequired- The catalog product ID, returned by product_create or products_list. System-generated IDs start with PROD-. Example: PROD-XXCD1234QWER65782
paypal_subscription_activateReactivate a suspended subscription so billing resumes.WriteActivate Subscription
Reactivate a suspended subscription so billing resumes. Returns an empty success (HTTP 204). Use subscription_activate after subscription_suspend; a reason is required when reactivating. A cancelled subscription cannot be reactivated.
Inputs
subscription_idstringrequired- The subscription ID (starts with I-), returned by subscription_create. Example: I-BW452GLLEP1G
reasonstring- Reason for the activate, 1 to 128 characters. Required when reactivating a suspended subscription. Example: Customer request
paypal_subscription_cancelCancel a subscription permanently; no further payments are taken and it cannot be reactivated.WriteCancel Subscription
Cancel a subscription permanently; no further payments are taken and it cannot be reactivated. Returns an empty success (HTTP 204). Use subscription_cancel to end a subscription for good. Use subscription_suspend to pause it instead.
Inputs
reasonstringrequired- Reason for the cancel, 1 to 128 characters. Example: Customer request
subscription_idstringrequired- The subscription ID (starts with I-), returned by subscription_create. Example: I-BW452GLLEP1G
paypal_subscription_captureCharge a subscriber now for the subscription's outstanding balance, for example after failed payments.WriteCapture Subscription Balance
Charge a subscriber now for the subscription's outstanding balance, for example after failed payments. Returns the resulting transaction with status and amount (HTTP 202 when it is still processing). Use subscription_capture to collect an outstanding balance. Use subscription_get to see the balance first under billing_info.outstanding_balance.
Inputs
amount_valuestringrequired- Amount to charge, up to the outstanding balance as a decimal string in the currency's units, for example 10.50 for ten dollars and fifty cents. Use whole numbers for currencies without decimals such as JPY. Set currency_code together with this field.
capture_typestringrequired- Type of capture. The only value is OUTSTANDING_BALANCE.one of
OUTSTANDING_BALANCE currency_codestringrequired- Three-letter ISO 4217 currency code for the charge, in upper case. Required whenever an amount is given. Example: USD
notestringrequired- Reason for the charge, 1 to 128 characters. Example: Charging outstanding balance
subscription_idstringrequired- The subscription ID (starts with I-), returned by subscription_create. Example: I-BW452GLLEP1G
request_idstring- Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a
paypal_subscription_createCreate a subscription to an active billing plan.WriteCreate Subscription
Create a subscription to an active billing plan. Returns the subscription with its id (I-...), status APPROVAL_PENDING and an approve link the subscriber must open to consent. Use subscription_create to enroll a customer, then subscription_get to confirm it became ACTIVE. Requires a plan_id from plan_create or plans_list.
Inputs
plan_idstringrequired- The billing plan to subscribe to (must be ACTIVE). Example: P-5ML4271244454362WXNWU5NQ
application_contextobject- Customizes the subscriber's approval page: return_url and cancel_url (both required in this object) say where the subscriber lands afterwards; you can also set brand_name, locale, shipping_preference (GET_FROM_FILE, NO_SHIPPING or SET_PROVIDED_ADDRESS) and user_action (SUBSCRIBE_NOW or CONTINUE). Example: {"brand_name": "Acme", "return_url": "https://example.com/return", "cancel_url": "https://example.com/cancel"}
custom_idstring- Your own reference for the subscription, such as an internal account or invoice id, up to 127 characters. Example: cust-2041
planobject- Optional overrides of the plan for this subscription only: billing_cycles (with sequence, total_cycles and pricing_scheme), payment_preferences and taxes. Example: {"billing_cycles": [{"sequence": 1, "total_cycles": 12, "pricing_scheme": {"fixed_price": {"currency_code": "USD", "value": "8.00"}}}]}
quantitystring- Quantity of the product, as a string, for plans with quantity_supported. Example: 2
request_idstring- Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a
shipping_amountobject- Shipping charge added to the subscription, with currency_code and value. Example: {"currency_code": "USD", "value": "5.00"}
start_timestring- When billing starts, as an ISO 8601 date-time in the future. Defaults to the current time. Example: 2026-11-01T00:00:00Z
subscriberobject- Subscriber details: email_address, name (given_name and surname), phone and shipping_address. Example: {"email_address": "customer@example.com", "name": {"given_name": "Jane", "surname": "Doe"}}
paypal_subscription_reviseSwitch a subscription to another plan, or change its quantity, shipping amount or shipping address, in a way that needs the subscriber's consent.WriteRevise Subscription
Switch a subscription to another plan, or change its quantity, shipping amount or shipping address, in a way that needs the subscriber's consent. Returns the revised subscription details and, when consent is needed, an approve link the subscriber must open. Use subscription_revise for plan or quantity changes. Use subscription_update for changes that need no consent.
Inputs
subscription_idstringrequired- The subscription ID (starts with I-), returned by subscription_create. Example: I-BW452GLLEP1G
application_contextobject- Customizes the subscriber's approval page: return_url and cancel_url (both required in this object) say where the subscriber lands afterwards; you can also set brand_name, locale, shipping_preference (GET_FROM_FILE, NO_SHIPPING or SET_PROVIDED_ADDRESS) and user_action (SUBSCRIBE_NOW or CONTINUE). Example: {"brand_name": "Acme", "return_url": "https://example.com/return", "cancel_url": "https://example.com/cancel"}
plan_idstring- The new plan to switch to. Example: P-5ML4271244454362WXNWU5NQ
quantitystring- New quantity of the product, as a string. Example: 3
shipping_addressobject- New shipping details: name (full_name) and address (address_line_1, admin_area_2 city, admin_area_1 state, postal_code, country_code). Example: {"name": {"full_name": "Jane Doe"}, "address": {"address_line_1": "2211 N First Street", "admin_area_2": "San Jose", "admin_area_1": "CA", "postal_code": "95131", "country_code": "US"}}
shipping_amountobject- New shipping charge with currency_code and value. Example: {"currency_code": "USD", "value": "5.00"}
paypal_subscription_suspendSuspend (pause) an active subscription so billing stops until it is reactivated.WriteSuspend Subscription
Suspend (pause) an active subscription so billing stops until it is reactivated. Returns an empty success (HTTP 204). Use subscription_suspend for a temporary pause and subscription_activate to resume. Use subscription_cancel to end it permanently.
Inputs
reasonstringrequired- Reason for the suspend, 1 to 128 characters. Example: Customer request
subscription_idstringrequired- The subscription ID (starts with I-), returned by subscription_create. Example: I-BW452GLLEP1G
paypal_subscription_updateUpdate an ACTIVE or SUSPENDED subscription using JSON Patch operations, for example its custom_id, shipping_amount, shipping address, billing_info.outstanding_balance, or plan overrides such as billing cycle prices and payment preferences.WriteUpdate Subscription
Update an ACTIVE or SUSPENDED subscription using JSON Patch operations, for example its custom_id, shipping_amount, shipping address, billing_info.outstanding_balance, or plan overrides such as billing cycle prices and payment preferences. Returns no body on success (HTTP 204). Use subscription_update for these fields. Use subscription_revise to switch plans or change quantity, which needs the subscriber's consent.
Inputs
patch_operationsarrayrequired- JSON Patch (RFC 6902) operations to apply. Each operation has an op (add, replace or remove), a path that is a JSON Pointer to the field, and, for add and replace, the new value. Patchable paths include /billing_info/outstanding_balance, /custom_id, /plan/billing_cycles/@sequence==1/pricing_scheme/fixed_price, /plan/payment_preferences/auto_bill_outstanding, /plan/taxes/percentage, /shipping_amount and /subscriber/shipping_address. Example: [{"op": "replace", "path": "/billing_info/outstanding_balance", "value": {"currency_code": "USD", "value": "50.00"}}]
subscription_idstringrequired- The subscription ID (starts with I-), returned by subscription_create. Example: I-BW452GLLEP1G
paypal_tracker_updateUpdate or cancel shipment tracking on a PayPal transaction; set status to CANCELLED to cancel it.WriteUpdate Tracker
Update or cancel shipment tracking on a PayPal transaction; set status to CANCELLED to cancel it. Returns an empty success (HTTP 204). Use tracker_update for trackers listed by trackers_list. Use order_tracker_update for trackers added to an order with order_tracking_add.
- Idempotent
Inputs
statusstringrequired- Shipment status: SHIPPED, ON_HOLD, DELIVERED, CANCELLED, LOCAL_PICKUP, SHIPMENT_CREATED, DROPPED_OFF, IN_TRANSIT, RETURNED, LABEL_PRINTED, ERROR or UNCONFIRMED. Use CANCELLED to cancel the tracker.one of
CANCELLEDDELIVEREDLOCAL_PICKUPON_HOLDSHIPPEDSHIPMENT_CREATEDDROPPED_OFFIN_TRANSITRETURNEDLABEL_PRINTEDERRORUNCONFIRMED tracker_idstringrequired- The tracker ID, which is the PayPal transaction ID and tracking number joined by a hyphen. Example: 8MC585209K746392H-443844607820
transaction_idstringrequired- The PayPal transaction ID the tracker belongs to. Example: 8MC585209K746392H
carrierstring- PayPal carrier code in upper case, such as USPS, UPS, FEDEX, DHL or ROYAL_MAIL. Required when tracking_number is set. Example: UPS
notify_buyerboolean- Set to true to email the buyer the tracking update. Defaults to false.
shipment_datestring- Date the item shipped, as YYYY-MM-DD. Example: 2026-10-14
tracking_numberstring- The carrier's tracking number. Requires carrier. Example: 443844607820
No tools match.
