Invoice endpoints
The following endpoints cover the full invoice lifecycle, from creating a draft to sending, updating, recording payments, and canceling.POST Create draft invoice
Creates 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.
Note: 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 invoice
Sends or schedules an invoice to be delivered to the customer, depending on the invoice issue date:
- If the issue date is today or in the past, PayPal sends the invoice immediately and changes the status to
SENT. - If the issue date is in the future, PayPal schedules and sends the invoice automatically on that date.
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:
- Resending an already-sent invoice has no effect.
- To notify the customer of an invoice update, update the invoice and set
send_to_recipient: true.
GET Show invoice details
Returns 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 invoices
Searches 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 invoice
Fully 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.
Note: The recipient (primary_recipients) can only be changed twice within a 72-hour window.
DELETE Delete invoice
Permanently 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 invoice
Cancels 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 reminder
Sends 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 payment
Records 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.
Note: Payments made through the PayPal-hosted invoice page are recorded automatically. Only use this endpoint for payments received through other channels.
DELETE Delete external payment
Deletes 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 invoice
Records 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.
Note: For refunds on payments processed through PayPal, use the Payments Refund API instead.
DELETE Delete external refund
Deletes 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 number
Generates 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 code
Generates 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.
Template endpoints
The following endpoints let you create and manage reusable invoice templates.POST Create template
Creates 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 templates
Returns 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 details
Returns 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 template
Fully 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 template
Permanently deletes an invoice template by ID. Existing invoices created from this template aren’t affected. You can’t delete standard PayPal-provided system templates.
Quick start using Invoicing API
Create and send your first invoice using the PayPal Invoicing API.
Use cases
Explore common invoicing scenarios and how to implement them.