- Create a draft invoice with minimum required fields
- Create a payment request linked to an external invoice
- Create an hourly services invoice
- Create an invoice for shippable goods
- Create an invoice for digital goods
- Create a mixed billing invoice
Prerequisites
- PayPal business account with Invoicing enabled.
- Obtain your sandbox credentials and access token. Refer to Get Started with PayPal REST APIs for more information.
- (Optional) Use a test email you can access, not your PayPal business email.
Use cases
See how to create invoices that address common scenarios and requirements.Create a draft invoice with minimum required fields
This is a good starting point for merchants new to the API or developers testing an integration before adding complexity.- Call
POST /v2/invoicing/invoiceswith minimal required fields. - Save the
idfrom the201 Createdresponse. - Call
POST /v2/invoicing/invoices/{id}/sendto deliver the invoice to the recipient.
| Field | Description |
|---|---|
detail.invoice_number | Your reference number for the invoice. |
detail.currency_code | Currency applied to all monetary values. |
detail.payment_term.term_type | When payment is due, such as DUE_ON_RECEIPT. |
invoicer | Sender name and email. |
primary_recipients | Customer name and email. |
items | At least one line item with name, quantity, and unit amount. |
201 Created. Save the returned id — you need it to send, update, or query the invoice.
Note: This creates aDRAFTinvoice. The customer isn’t notified until you callPOST /v2/invoicing/invoices/{id}/send.
Create a payment request linked to an external invoice
This pattern is ideal for merchants using a enterprise resource planning (ERP) or accounting platforms like NetSuite, QuickBooks, or Xero who want to collect payment through PayPal without recreating the invoice. Pass the external reference viainvoice_number or detail.reference, and optionally attach the original invoice PDF.
- Create the invoice in your external system and capture the external invoice ID.
- Call
POST /v2/invoicing/invoicesto create a PayPal payment request, passing the external invoice ID and optionally attaching the original invoice PDF. - Call
POST /v2/invoicing/invoices/{id}/sendto deliver the payment request to the customer. - The customer receives a PayPal-hosted payment link by email and pays using PayPal or a card.
| Field | Description |
|---|---|
items[].unit_of_measure: "AMOUNT" | Flat-rate billing with no quantity or hourly breakdown. |
attachments | Attach the original invoice PDF for the customer’s reference. |
invoice_number
detail.reference
- Use
unit_of_measure: "AMOUNT"when billing a flat total with no quantity or hourly breakdown. - The
attachmentsarray accepts publicly accessible URLs. The PDF must be reachable by PayPal’s servers at the time you create the invoice. detail.referenceis visible to the customer on the PayPal invoice page. This is useful for cross-referencing the external invoice number.detail.memois a private field visible only to the invoicer. Use this for internal bookkeeping notes.
Create an hourly services invoice
Create an hourly services invoice withunit_of_measure: "HOURS", a client billing address, tip enabled, and partial payment configured for deposit workflows. This pattern works best for consultants, freelancers, photographers, and tradespeople billing for time and labor.
- Confirm the scope, hours, and rate for completed service work.
- Call
POST /v2/invoicing/invoiceswith hourly or amount-based line items and the client’s billing address. Don’t includeshipping_info. - Call
POST /v2/invoicing/invoices/{id}/sendto deliver the invoice to the client. - The client receives the invoice and pays with PayPal or card.
| Field | Description |
|---|---|
items[].unit_of_measure: "HOURS" | Renders quantity as hours worked and unit_amount as the hourly rate. |
primary_recipients[].billing_info.address | Client billing address; no shipping_info included. |
detail.payment_term.term_type | When payment is due, such as NET_14 or NET_30. |
detail.note | Project summary or message visible to the client. |
detail.term | Formal payment terms and conditions. |
configuration.allow_tip: true | Enables an optional tip or gratuity field on the PayPal-hosted payment page. |
configuration.partial_payment | Supports deposit or installment payment workflows. |
unit_of_measure: "HOURS"renders quantity as hours andunit_amountas the hourly rate on both the invoice and the customer-facing payment page.- Omitting
shipping_infofromprimary_recipientsindicates a non-shippable, services-based invoice. Onlybilling_infois required. allow_tip: truerenders an optional tip or gratuity field on the PayPal-hosted payment page — no additional API calls required. Use this for service businesses where tipping is customary, such as trades, personal care, event services, or photography. Setallow_tip: falsefor B2B or formal invoicing contexts.allow_partial_payment: truewith aminimum_amount_duesupports deposit-first or installment workflows common in service businesses.- Use
unit_of_measure: "AMOUNT"instead of"HOURS"if you’re billing a flat project fee rather than hourly. - To record a payment received outside of PayPal, such as by check or bank transfer, use
POST /v2/invoicing/invoices/{id}/payments.
Create an invoice for shippable goods
Create a physical goods invoice with quantity-based line items, separate billing and shipping addresses, a shipping charge, and shipping-specific tax. This pattern works best for e-commerce sellers, wholesalers, and distributors shipping physical products.- Confirm the products, quantities, and shipping details from the order in your system.
- Call
POST /v2/invoicing/invoiceswith quantity-based line items, a shipping address, and a shipping charge. - Call
POST /v2/invoicing/invoices/{id}/sendto deliver the invoice. - The buyer pays via PayPal or card; fulfill and ship the order.
| Field | Description |
|---|---|
primary_recipients[].shipping_info | Buyer’s shipping address. This can differ from billing address. |
primary_recipients[].billing_info | Buyer’s billing address. |
items[].unit_of_measure: "QUANTITY" | Unit-based billing for physical goods. |
amount.breakdown.shipping.amount | Flat shipping charge. |
amount.breakdown.shipping.tax | Tax applied specifically to the shipping charge. |
items[].tax | Per-line sales tax on individual goods. |
detail.reference | Purchase order or order reference number. This value is customer-visible. |
shipping_infoandbilling_infocan have different addresses — PayPal renders both on the invoice and buyer confirmation page.unit_of_measure: "QUANTITY"renders items as discrete units — the standard for physical goods.- Shipping tax is defined separately in
amount.breakdown.shipping.taxand is independent from line item taxes. detail.referenceis customer-visible and useful for linking back to a purchase order or external order management reference.- To record a payment received outside of PayPal, such as by check or bank transfer, use
POST /v2/invoicing/invoices/{id}/payments.
Create an invoice for digital goods
Create a digital goods invoice with unit and flat-rate line items and a billing address only — no shipping address or charges. This pattern works best for merchants selling software licenses, downloads, online courses, or other digital products.- Capture the order details for the digital product purchase in your system.
- Call
POST /v2/invoicing/invoiceswith digital line items and a billing address only. Don’t includeshipping_info. - Call
POST /v2/invoicing/invoices/{id}/sendto deliver the invoice. - The customer pays via PayPal or card; handle digital delivery separately.
| Field | Description |
|---|---|
items[].unit_of_measure: "QUANTITY" | Unit-based billing for seat or license-based products. |
items[].unit_of_measure: "AMOUNT" | Flat-rate billing for bundles or one-time packages. |
primary_recipients[].billing_info | Billing address only; no shipping_info included. |
items[].tax | Applicable sales tax. Digital goods tax rules vary by jurisdiction. |
detail.note | Delivery instructions or next-step guidance visible to the customer after payment. |
- Omitting
shipping_infofromprimary_recipientssignals that no physical delivery is required. - Use
unit_of_measure: "QUANTITY"for seat or unit-based products. Use"AMOUNT"for flat-rate bundles or packages where itemized quantity doesn’t apply. - Digital goods tax rules vary significantly by jurisdiction — consult your tax advisor for the correct rate based on customer location.
- Use
detail.noteto communicate delivery instructions or access information. This field is customer-visible on the PayPal invoice and payment confirmation page.
Create a mixed billing invoice
Create an invoice that combines all threeunit_of_measure types — HOURS, QUANTITY, and AMOUNT — in a single request, with an invoice-level discount and partial payment configuration. This pattern works best for agencies, consultancies, and IT services firms billing for a mix of time, deliverables, and flat fees within the same engagement.
Note: This is an advanced use case that builds on the patterns above. If your business bills using only one line item type, refer to the appropriate use case.
- Confirm time logs, deliverable counts, and agreed flat fees for the completed project work.
- Call
POST /v2/invoicing/invoiceswith mixed line items combiningHOURS,QUANTITY, andAMOUNTtypes. - Review the draft, then call
POST /v2/invoicing/invoices/{id}/send. - The client receives the invoice, reviews the itemized breakdown, and pays via PayPal or card.
| Field | Description |
|---|---|
items[].unit_of_measure: "HOURS" | Billable time; quantity = hours worked, unit_amount = hourly rate. |
items[].unit_of_measure: "QUANTITY" | Discrete units; quantity = number of items, unit_amount = unit price. |
items[].unit_of_measure: "AMOUNT" | Flat-rate charge; quantity = "1", unit_amount = total flat fee. |
items[].discount | Line item-level discount, such as percent or fixed amount. |
amount.breakdown.discount | Invoice-level discount applied across all line items. |
configuration.partial_payment | Supports structured deposit and balance workflows. |
detail.memo | Private internal note, not visible to the client. |
- You can mix all three
unit_of_measuretypes —HOURS,QUANTITY, andAMOUNT— freely within the sameitemsarray. Each line item renders according to its own type on the invoice. - Use
quantity: "1"onAMOUNTlines for flat-rate fees. Don’t use a quantity greater than"1"on anAMOUNTline — the API multiplies the values, which is likely unintended for flat fees. - The invoice-level
amount.breakdown.discountapplies across the entire invoice total after individual line item subtotals are summed. Line item-level discounts apply before the invoice-level discount. - Set
configuration.tax_calculated_after_discount: trueto calculate tax on the post-discount amount — the correct behavior for most jurisdictions. detail.memois private and never shown to the client — use it for internal bookkeeping, account references, or sales attribution.
Invoicing API
The Invoicing REST API lets you create, update, send, and manage invoices programmatically from your backend systems.
Troubleshooting
Resolve common Invoicing API errors and integration issues.