On this page
No Headings
Last updated: June 4, 2026
Estimated time: 6 minutes
Use the PayPal Invoicing API to create, send, and manage invoices programmatically. This page covers all endpoints, request parameters, response objects, and error codes. For full schema definitions and interactive examples, see the Invoicing API reference.
The following endpoints cover the full invoice lifecycle, from creating a draft to sending, updating, recording payments, and canceling.
POST Create draft invoiceCreates a draft invoice. The customer isn't notified until you call POST /v2/invoicing/invoices/{id}/send. Include an items array and merchant information in the invoicer object.
A successful request returns HTTP 201 Created and a PayPal-assigned invoice id. Save this ID because you'll need it for all subsequent operations, including sending, updating, recording payments, and generating QR codes.
The merchant account must be in good standing with PayPal. For partner integrations acting on behalf of a merchant, include the PayPal-Auth-Assertion header.
POST Send invoiceSends or schedules an invoice to be delivered to the customer, depending on the invoice issue date:
SENT.Set send_to_recipient: false to move the invoice to payable state without emailing the customer. This is useful when sharing the payment link yourself or generating a QR code. Set send_to_invoicer: false to suppress the merchant copy of the notification.
Notes:
send_to_recipient: true.GET Show invoice detailsReturns the full invoice object for a given invoice ID, including current status, line items, recipient information, payment and refund history, and HATEOAS links for available next actions. Use this to check invoice state, retrieve the customer-facing payment URL (detail.metadata.recipient_view_url), or verify recorded payments.
POST Search for invoicesSearches for invoices matching multiple criteria simultaneously. All specified criteria must match. Supports filtering by recipient email, invoice status, date range, amount range, currency, reference number, memo, and item description.
Use this endpoint when you need to combine multiple filters that aren't available as query parameters on GET /v2/invoicing/invoices.
PUT Fully update invoiceFully replaces an invoice by ID. The request body must include the complete invoice object, and any fields omitted are cleared. To safely update a single field, first retrieve the current invoice with GET /v2/invoicing/invoices/{id}, modify the required fields, then resubmit the full object.
The recipient (primary_recipients) can only be changed twice within a 72-hour window.
DELETE Delete invoicePermanently deletes a draft or scheduled invoice by ID. For sent invoices, use POST /v2/invoicing/invoices/{id}/cancel instead. You can't recover or query the invoice after deletion, but you can reuse the invoice number.
POST Cancel sent invoiceCancels a sent invoice and changes its status to CANCELLED. For invoices that were never sent, use DELETE /v2/invoicing/invoices/{id} instead. PayPal retains canceled invoices for record-keeping, and you can still query them. Optionally sends cancellation notifications to the customer, merchant, and CC recipients.
POST Send invoice reminderSends a payment reminder email to the customer for an unpaid invoice. Use this to follow up on overdue invoices or prompt payment before the due date.
Limit: You can send up to 2 reminders per invoice per day.
POST Record external paymentRecords an offline payment against an invoice, for example, cash, check, bank transfer, or wire payment received outside of PayPal. PayPal updates the invoice status to MARKED_AS_PAID if the full balance is covered, or PARTIALLY_PAID if a partial amount is recorded.
Payments made through the PayPal-hosted invoice page are recorded automatically. Only use this endpoint for payments received through other channels.
DELETE Delete external paymentDeletes a previously recorded offline payment from an invoice. Use this to correct a payment entry recorded in error via POST /v2/invoicing/invoices/{id}/payments. Doesn't affect payments processed through PayPal's hosted payment page.
POST Record refund for invoiceRecords an offline refund against a paid invoice, for example, a refund issued through cash, check, or bank transfer outside of PayPal. Updates the invoice status to MARKED_AS_REFUNDED if fully refunded, or PARTIALLY_REFUNDED if a partial amount is recorded.
For refunds on payments processed through PayPal, use the Payments Refund API instead.
DELETE Delete external refundDeletes a previously recorded offline refund from an invoice. Use this to correct a refund entry recorded in error through POST /v2/invoicing/invoices/{id}/refunds. Doesn't affect refunds processed through PayPal.
POST Generate invoice numberGenerates the next sequential invoice number for the authenticated merchant, incrementing from the last used number and preserving any prefix or suffix pattern. For example, the next number after INVOICE-1234 is INVOICE-1235.
Use this when you want PayPal to automatically manage invoice numbering. To use your own reference system, such as an ERP or accounting platform order ID, pass a custom invoice_number directly in the create draft invoice request instead.
POST Generate QR codeGenerates a Base64-encoded PNG QR code for a sent invoice. Add it to a paper or PDF invoice — when a customer scans it with a mobile device they are redirected to a PayPal-hosted payment page to pay using PayPal or card.
The invoice must be in SENT status before generating a QR code. To move an invoice to payable state without emailing the customer, set send_to_recipient: false in the send invoice request.
The following endpoints let you create and manage reusable invoice templates.
POST Create templateCreates a reusable invoice template that pre-populates fields — such as merchant information, line items, payment terms, and tax configuration — when creating new invoices. Templates reduce repetitive data entry for merchants who regularly send the same invoice type.
To apply a template when creating an invoice, pass the template_id in the configuration object of POST /v2/invoicing/invoices. Merchants can create up to 50 templates.
GET List templatesReturns a list of merchant-created invoice templates, including associated business information such as emails, addresses, and phone numbers from the merchant's PayPal profile. Use the returned template_id when creating invoices to pre-populate fields from a saved configuration.
GET Show template detailsReturns the full template object for a given template ID, including all configured fields, display settings, line item defaults, and payment configuration. Retrieve this before a full update to avoid unintentionally clearing fields.
PUT Fully update templateFully replaces an invoice template by ID. The request body must include the complete template object — fields omitted will be cleared. Retrieve the current template with GET /v2/invoicing/templates/{id} before updating to avoid unintended data loss.
Updates to a template don't affect invoices previously created from it.
DELETE Delete templatePermanently deletes an invoice template by ID. Existing invoices created from this template aren't affected. You can't delete standard PayPal-provided system templates.