Which strategy should I use for PayPal Invoicing v1 to Invoicing v2 Migration?
Choose whether to keep supporting PayPal Invoicing v1 for existing merchants or migrate to Invoicing v2 now that v1 is a deprecated resource and v2 changes error handling and partner workflows.
Blockers
- replaces: package/paypal-invoicing-v2 → package/paypal-invoicing-v1
- breaking_change_in: package/paypal-invoicing-v1 → package/paypal-invoicing-v2
- replaces: capability/integrated-sign-up → package/paypal-invoicing-v1
Who this is for
- enterprise
- compliance
Candidates
Keep PayPal Invoicing v1 only for existing merchants in maintenance mode
As of 2026-04-09, PayPal marks the `/v1/invoicing/invoices` resource as deprecated and says deprecated resource pages exist to support customers with existing integrations only. PayPal's invoicing docs say there is no fee to use the Invoicing APIs, but fees for receiving payments vary by country and other fees can apply for currency conversion or cross-border receipt. The older integration model documents partner service providers using Log in with PayPal to obtain merchant authorization. v1 keeps older endpoint shapes such as separate `/send` and `/schedule` actions, `record-payment` and `record-refund` paths, and GET-based QR code generation.
When to choose
Use this only when you already have live merchants on v1 and need the lowest-risk short-term support path while you plan migration. The decisive factor is whether avoiding immediate integration churn matters more than staying on PayPal's current recommended surface.
Tradeoffs
Least disruptive in the short term and preserves current merchant behavior, but it leaves you on a deprecated API family that PayPal no longer positions for new integrations. You also give up v2's Integrated Sign-Up positioning and richer error payloads.
Cautions
Do not extend v1 for new merchant onboarding. v1 has integration-specific behavior you must preserve during maintenance, including a separate `/schedule` endpoint, `notify_merchant` query semantics, older payment and refund route names, GET `/qr-code`, and the documented note that after sending an invoice you cannot resend it from the send endpoint.
Migrate to PayPal Invoicing v2 now
As of 2026-04-09, PayPal's deprecated resources page directs Invoicing users from v1 to v2 and highlights three upgrade benefits: alignment with common PayPal API components, Integrated Sign-Up for ecommerce platforms and merchant service providers, and improved error messaging. PayPal's invoicing docs still say there is no fee to use the Invoicing APIs, while payment-receipt fees vary by country. v2 changes operational behavior and payloads: the send endpoint also schedules future-dated invoices, notification flags move into the request body, payment and refund endpoints become `/payments` and `/refunds`, external transaction delete paths are renamed, and QR generation moves to POST `/generate-qr-code`. The v2 error schema is materially richer, including `value`, `location`, `description`, and issue-related links in error details.
When to choose
Use this for any new merchant onboarding, partner platform work, or any roadmap where you expect PayPal invoicing support to continue beyond a short maintenance window. The decisive factor is that v2 is the current recommended API and already carries the partner-workflow and error-model improvements PayPal is steering integrators toward.
Tradeoffs
You pay migration cost now, but you remove dependency on a deprecated resource and align with PayPal's current API direction. The cost is real because route names, notification handling, QR generation, and some request and response shapes are not drop-in compatible with v1.
Cautions
Budget for adapter and test work rather than a path-only swap. In particular, rework send and schedule flows, map old `record-payment` and `record-refund` calls to v2 payment and refund resources, update any code that deletes external transactions, and adjust error parsing because v2 returns a more structured error object than v1.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Which strategy should I use for PayPal Invoicing v1 to Invoicing v2 Migration?"