Core resources
The API centers on the following three primary resources: invoices, templates, and payment records.Invoice
An invoice is a hosted payment request that PayPal delivers to your customer and manages through different states over its lifecycle. Unlike a static PDF, an invoice is a dynamic object that moves through distinct states from creation to payment, refund, or cancellation. Each state determines what actions are available. When you send an invoice, PayPal generates a secure payment page where the customer can view line items and pay using PayPal, a credit card, a debit card, or other eligible payment methods. Customers access this page from a PayPal-issued email link or a QR code you generate.Templates
A template is a reusable invoice configuration that pre-populates common fields, including merchant details, default line items, payment terms, tax settings, and branding. Templates decouple invoice design from invoice creation. Instead of hardcoding these values into each request, you create a template and reference it by ID. PayPal inherits default values, including merchant name, email, address, logo, default tax rates, and payment terms, when you create an invoice from that template. You can override any template value in the invoice request. The invoice is independent of the template after creation, so updating a template doesn’t affect invoices already created from it. You can create up to 50 templates. PayPal provides standard system templates that you can’t delete.Payment and refund records
The API distinguishes between two types of payment recording.- Automatic payment recording: When customers pay through PayPal’s hosted invoice page, PayPal automatically records the transaction and updates the invoice status.
- Manual payment recording: For payments received outside PayPal, such as checks, bank transfers, or cash, explicitly call the Record External Payment endpoint to document receipt. This is critical for integrating with non-PayPal payment channels.
Invoice lifecycle
| State | Description |
|---|---|
DRAFT | The invoice exists, but the customer hasn’t been notified. You can edit all fields freely. |
SENT | The invoice is delivered and payable. The customer is notified unless you suppress notification. You can’t return a sent invoice to DRAFT. If the invoice has a future issue date, PayPal holds it and sends it automatically on that date. |
PARTIALLY_PAID | A partial payment has been recorded. The balance decreases, but the invoice stays open. |
PAID | The full amount was paid through PayPal’s hosted page. |
MARKED_AS_PAID | The full amount was recorded manually via the Record External Payment endpoint. |
REFUNDED | The invoice was fully refunded through PayPal. |
MARKED_AS_REFUNDED | A full refund was recorded manually. |
PARTIALLY_REFUNDED | A partial refund was issued. The balance increases accordingly. |
CANCELLED | The invoice was canceled after being sent. Canceled invoices are retained for audit purposes and remain queryable. To remove a draft invoice, delete it instead. You can’t cancel a draft. |
DRAFT until you send them so customers aren’t notified of an incomplete or incorrect request. After you send it, the invoice represents a formal payment commitment. You can cancel it, but you can’t unsend it. Canceled invoices are retained for audit purposes rather than deleted, which supports compliance and dispute resolution.
Billing types
Each line item on an invoice uses one of three unit-of-measure types. A single invoice can combine all three.| Type | Best for | Example |
|---|---|---|
QUANTITY | Discrete, countable items | 2 widgets at $50 each |
HOURS | Time-based services | 12 hours $150/hour |
AMOUNT | Flat-rate charges with no quantity breakdown | Consultation: $500 |
External system integration
If you manage invoices in an external system, such as an ERP or accounting platform, two fields let you bridge it with your system.- Use
detail.invoice_numberto store your external invoice ID, for exampleNETSUITE-INV-78432. This value is customer-visible and must be unique within your PayPal invoices. - Use
detail.referencefor cross-referencing order or PO numbers. This field is also visible to customers on the PayPal payment page.
Authentication
The Invoicing API uses OAuth 2.0. Every request requires an access token in theAuthorization header. The token is scoped to specific operations. The https://api.paypal.com/v1/invoicing:* scope grants full access to invoicing operations.
- Access token expiration: Tokens expire after approximately 9 hours. There’s no refresh token. Request a new access token using your client credentials when the current one expires. Cache the token with its expiration date timestamp and refresh it proactively rather than waiting for a
401response. - Partner integrations: If you act on behalf of multiple merchants, include the
PayPal-Auth-Assertionheader on each request. This signed header identifies which merchant you’re operating for, and PayPal applies the corresponding merchant context and permissions. - Idempotency: Use the
PayPal-Request-Idheader to make requests idempotent. If a network error causes a request to fail, retry with the same request ID. PayPal recognizes the duplicate and returns the original result without creating a duplicate invoice or recording a duplicate payment.