PayPal

Payments and billing. Create and capture orders, authorize and refund payments, send payouts, issue invoices, and run subscriptions.

Measured routing accuracy

51 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 37 cases written by hand and 14 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

One of the 38 action tools listed above is declared uncallable, so it is indexed nowhere and answers none of these cases. The counts here are scored over the other 37.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

oauth2

api_key

Submit the key with ConnectionsService rather than putting it in a request; it is sealed at rest and never returned.

Tools

38 action tools. The catalog-wide slug is paypal.<tool>, which is what search_tools returns and call_tool takes.

paypal.create_order

Create a PayPal order for a checkout, specifying the amount to authorize or capture. Use when the user wants to start, set up, or begin a PayPal payment or checkout before the buyer approves it. Intent controls whether funds are captured immediately or just held.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v2/checkout/orders.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "set up a checkout for this purchase", "get a paypal payment going for the buyer", "I need to bill someone through paypal", "open a new transaction for this sale", "start a paypal checkout session".

paypal.get_order

Get one PayPal order by id: its status, amount, and buyer details. Use when the user asks whether an order was approved, wants to check a checkout's state, or names a specific order id.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v2/checkout/orders/{{params.order_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did the buyer approve this yet", "check the state of this checkout", "what's happening with this transaction", "pull up the details on this purchase".

paypal.update_order

Change a field on an existing PayPal order before it is captured, such as its amount or description. Use when the user wants to correct or adjust an order that has not been paid yet. For paying it, use capture_order or authorize_order instead.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PATCH /v2/checkout/orders/{{params.order_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fix the amount on this checkout before it's paid", "the buyer needs a different total on this purchase", "correct something on this pending transaction".

paypal.authorize_order

Place a hold on funds for an approved PayPal order without collecting them yet. Use when the user wants to authorize, pre-approve, or reserve payment before shipping, then capture the hold later with capture_authorized_payment.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v2/checkout/orders/{{params.order_id}}/authorize.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "put a hold on the buyer's card for now", "reserve the funds but don't take them yet", "lock in the money until we ship".

paypal.capture_order

Collect payment on an approved PayPal order right away. Use when the user wants to charge, capture, or finish collecting on an order the buyer has approved. For an order that only holds funds so far, capture the resulting authorization with capture_authorized_payment instead.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v2/checkout/orders/{{params.order_id}}/capture.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "go ahead and take the buyer's money", "finish collecting on this purchase", "actually charge them for the sale", "process the payment they approved".

paypal.get_authorization

Get one payment authorization by id: its status, held amount, and expiration time. Use when the user asks whether a hold is still valid or how much was reserved on a card or PayPal balance.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v2/payments/authorizations/{{params.authorization_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "is that hold still good", "check how much we reserved on their card", "when does this reserved amount expire".

paypal.capture_authorized_payment

Capture funds from a payment authorization that is currently held. Use when the user wants to collect, take, or finalize a hold placed earlier, e.g. once an order has shipped. Supports a partial amount and marking it the final capture.

Class write (writes, no confirmation needed). Scopes https://uri.paypal.com/services/payments/payment. Calls POST /v2/payments/authorizations/{{params.authorization_id}}/capture.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "grab the funds we reserved earlier", "collect on that hold now that we shipped", "finalize the money we set aside", "take the reserved amount now".

paypal.void_authorization

Void a payment authorization, releasing its held funds back to the payer without collecting anything. Irreversible; a voided authorization cannot be captured afterward. Use when the user wants to void, release, or drop a hold that will never be charged.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /v2/payments/authorizations/{{params.authorization_id}}/void.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "release that hold, we don't need it", "never mind, let go of the reserved funds", "cancel the reservation on their card", "drop the pending hold entirely".

paypal.get_capture

Get one payment capture by id: its status, amount, and whether it has been refunded. Use when the user asks about a specific completed PayPal charge. For refunding it, use refund_capture.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v2/payments/captures/{{params.capture_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "was this specific charge refunded", "look up the details on a completed transaction", "pull up this finished payment".

paypal.refund_capture

Refund a captured PayPal payment, in full or in part. Irreversible once processed; the money returns to the payer's original funding source. Use when the user wants to refund, reverse, or give money back for a completed charge.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://uri.paypal.com/services/payments/refund. Calls POST /v2/payments/captures/{{params.capture_id}}/refund.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "give the buyer their money back", "reverse this transaction", "send money back to whoever paid", "undo this charge, they want a refund", "return funds for this purchase".

paypal.get_refund

Get one refund by id: its status, amount, and the capture it applies to. Use when the user asks whether a specific PayPal refund went through or how much was returned.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v2/payments/refunds/{{params.refund_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did that money-back request go through", "check the status of a returned payment", "how much did we send back".

paypal.create_payout

Send a PayPal payout of money to one or more recipients by email, phone, or PayPal account id. Irreversible once processed; funds move immediately to a claimed recipient. Use when the user wants to pay out, disburse, or send money to sellers, affiliates, or workers in bulk.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://uri.paypal.com/services/payments/payouts. Calls POST /v1/payments/payouts.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pay these people through paypal", "send money to a bunch of sellers at once", "disburse funds to our affiliates", "wire everyone their earnings this week", "bulk pay a list of recipients".

paypal.get_payout

Get the status of a whole PayPal payout batch by its id, including every item in it. Use when the user asks whether a bulk payout run finished or wants a summary of a batch. For one recipient's status, use get_payout_item.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v1/payments/payouts/{{params.payout_batch_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did the bulk payment run finish", "check on that mass payment we sent out", "what's the status of everyone getting paid".

paypal.get_payout_item

Get one recipient's status within a payout batch: whether it was claimed, is pending, or failed. Use when the user asks about a single person's payout rather than the whole batch.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v1/payments/payouts-item/{{params.payout_item_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did this one person get their money", "check if a specific recipient claimed their payout", "is this payment to them still pending".

paypal.cancel_payout_item

Cancel one unclaimed item in a payout batch, returning those funds to the sender's balance. Only works while the recipient has not yet claimed it. Use when the user wants to cancel, pull back, or stop an unclaimed payout to one person.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://uri.paypal.com/services/payments/payouts. Calls POST /v1/payments/payouts-item/{{params.payout_item_id}}/cancel.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull back the money we sent them, they never claimed it", "stop this one payout before it's picked up", "take back an unclaimed payment".

paypal.create_invoice

Create a draft PayPal invoice billing a recipient for one or more line items. Use when the user wants to draft, start, or open a new invoice or bill before sending it. Send it afterward with send_invoice.

Class write (writes, no confirmation needed). Scopes https://uri.paypal.com/services/invoicing. Calls POST /v2/invoicing/invoices.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "draft a bill for this client", "I need to invoice someone through paypal", "set up a paypal bill before I send it", "start a new invoice for consulting work".

paypal.get_invoice

Get one PayPal invoice by id: its status, amount due, amount paid, and recipient. Use when the user names a specific invoice or asks whether it has been paid.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v2/invoicing/invoices/{{params.invoice_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "has this bill been paid yet", "pull up the details on this bill", "check what's owed on this invoice".

paypal.list_invoices

Search PayPal invoices by recipient email or status such as draft, sent, or paid. Use when the user asks about a customer's invoices, unpaid bills, or billing history. For one known invoice, use get_invoice.

Class read (reads only). No scopes beyond the connection's defaults. Calls POST /v2/invoicing/invoices/search-invoices.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what bills are still unpaid", "show every invoice we've sent this client", "search for their outstanding invoices", "what's our billing history look like".

paypal.update_invoice

Replace the details of a draft PayPal invoice: its line items, note, or due date. Use when the user wants to edit, fix, or change a draft invoice before it has been sent. Only works while the invoice is still a draft.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /v2/invoicing/invoices/{{params.invoice_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fix a line item before I send this bill", "the due date on this draft bill is wrong", "change something on this unsent invoice".

paypal.send_invoice

Email a draft PayPal invoice to its recipient so they can pay it. Use when the user wants to send, deliver, or mail an invoice to whoever owes it. Moves the invoice from draft to sent.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v2/invoicing/invoices/{{params.invoice_id}}/send.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "email this bill to the client", "go ahead and deliver the invoice", "get this bill in front of whoever owes it".

paypal.cancel_invoice

Cancel a PayPal invoice that has already been sent, notifying the recipient it no longer needs paying. Irreversible; the invoice stays on record marked cancelled instead of being deleted. Use when the user wants to void, kill, or invalidate an invoice sent by mistake.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /v2/invoicing/invoices/{{params.invoice_id}}/cancel.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "this bill was sent by mistake, kill it", "the client doesn't owe this anymore", "void a bill that already went out".

paypal.delete_invoice

Permanently delete a draft PayPal invoice that has not been sent. Irreversible and only works while the invoice is still a draft. For a sent invoice that should never be paid, use cancel_invoice instead.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v2/invoicing/invoices/{{params.invoice_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "scrap this draft bill entirely", "get rid of an invoice before it's sent", "wipe this unsent bill out".

paypal.create_product

Create a product in the PayPal catalog, to attach a billing plan to later. Use when the user wants to add or register a new product or service they will sell through PayPal subscriptions. Follow with create_plan to price it.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v1/catalogs/products.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "register what we're selling for subscriptions", "add a new offering to the catalog", "set up a service we'll bill recurring for".

paypal.get_product

Get one PayPal catalog product by id: its name, type, and category. Use when the user names a specific product they sell through PayPal.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v1/catalogs/products/{{params.product_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up details on this catalog listing", "what is this thing we sell", "check the category on this item".

paypal.list_products

List products in the PayPal catalog. Use when the user asks what products or services are set up for subscriptions, or wants to browse the catalog before creating a plan.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v1/catalogs/products.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what do we have set up to subscribe to", "browse everything in our catalog", "show me our subscription offerings".

paypal.create_plan

Create a billing plan on a PayPal product, setting its recurring price and frequency. Use when the user wants to set up, define, or price a new subscription plan or tier. Subscribe someone to it with create_subscription.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v1/billing/plans.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "price out a new subscription tier", "set the monthly cost for this plan", "define how much and how often we charge".

paypal.get_plan

Get one PayPal billing plan by id: its price, frequency, and whether it is active. Use when the user asks what a specific subscription plan or tier costs or includes.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v1/billing/plans/{{params.plan_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what does this subscription tier cost", "pull up the pricing on this plan", "is this tier still active".

paypal.list_plans

List billing plans, optionally filtered by product or status. Use when the user asks what subscription plans or pricing tiers exist for a product. For one known plan, use get_plan.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v1/billing/plans.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what tiers do we offer for this product", "show every pricing option available", "browse the billing tiers on this product".

paypal.update_plan_pricing

Change the recurring price of an existing PayPal billing plan. Use when the user wants to raise, lower, or repriced a subscription plan for its billing cycle. Existing subscribers move to the new price on their next renewal.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v1/billing/plans/{{params.plan_id}}/update-pricing-schemes.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "raise the price on this subscription tier", "change what we charge going forward", "reprice this plan for new subscribers".

paypal.deactivate_plan

Deactivate a PayPal billing plan so no one can subscribe to it again. Irreversible through this action; existing subscribers keep billing normally. Use when the user wants to retire, sunset, or discontinue a subscription plan or tier.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /v1/billing/plans/{{params.plan_id}}/deactivate.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "retire this subscription tier", "stop letting people sign up for this plan", "sunset an old pricing option".

paypal.create_subscription

Start a recurring PayPal subscription for a subscriber on a billing plan. Use when the user wants to subscribe, sign up, or put someone on a recurring PayPal plan. The subscriber approves it through the returned PayPal link before billing starts.

Class write (writes, no confirmation needed). Scopes https://uri.paypal.com/services/subscriptions. Calls POST /v1/billing/subscriptions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "sign this person up for a recurring plan", "put them on a subscription", "enroll a customer in our monthly billing".

paypal.get_subscription

Get one PayPal subscription by id: its status, plan, next billing time, and any outstanding balance. Use when the user asks about a specific customer's plan or subscription state.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v1/billing/subscriptions/{{params.subscription_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "when do they get billed next", "check the state of this customer's plan", "is this subscription still active".

paypal.update_subscription

Change an active PayPal subscription's plan or quantity. Use when the user wants to upgrade, downgrade, or swap a subscriber to a different plan or tier. To end it instead of changing it, use cancel_subscription.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v1/billing/subscriptions/{{params.subscription_id}}/revise.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "move them to a different tier", "upgrade this customer's plan", "swap them onto a new subscription level".

paypal.suspend_subscription

Pause an active PayPal subscription so billing stops until it is reactivated. Use when the user wants to pause, freeze, or put a subscription on hold without canceling it outright. Resume it later with reactivate_subscription.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v1/billing/subscriptions/{{params.subscription_id}}/suspend.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pause their billing for now", "freeze this subscription temporarily", "put their plan on hold".

paypal.reactivate_subscription

Resume a suspended PayPal subscription, restarting its billing cycle. Use when the user wants to reactivate, unpause, or bring back a subscription that was previously paused.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v1/billing/subscriptions/{{params.subscription_id}}/activate.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "turn their subscription back on", "resume billing for this customer", "unpause a plan we froze earlier".

paypal.cancel_subscription

End a PayPal subscription immediately, stopping all future billing. Irreversible; a canceled subscription cannot be resumed and needs a new one. Use when the user wants to cancel, stop, or terminate a subscription entirely, not just pause it.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /v1/billing/subscriptions/{{params.subscription_id}}/cancel.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "end this recurring plan for good", "the customer wants to stop their subscription", "terminate their billing entirely".

paypal.capture_subscription_payment

Capture an outstanding balance on a PayPal subscription right away, such as a failed renewal charge. Use when the user wants to collect, retry, or force payment on a subscription's unpaid balance rather than waiting for the next billing cycle.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v1/billing/subscriptions/{{params.subscription_id}}/capture.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "collect what they owe on their plan right now", "retry a failed renewal charge", "force through the balance they still owe".

paypal.list_subscription_transactions

List the billing transactions for a PayPal subscription over a date range: each charge, its status, and amount. Use when the user asks for a subscription's payment history or wants to see what a customer has been charged over time.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v1/billing/subscriptions/{{params.subscription_id}}/transactions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "show everything this subscriber has been charged", "pull their billing history for the plan", "what payments has this customer made over time".