On this page
No Headings
Last updated: June 4, 2026
Estimated time: 10 minutes
An invoice is a payment request you send to a customer for goods or services delivered. In the PayPal Invoicing API, invoices flow through a lifecycle: created as DRAFT, sent to customers, tracked through payment states (UNPAID, PARTIALLY_PAID, PAID), and optionally refunded.
The invoice object represents a complete invoice including sender and recipient details, line items, amounts, payment configuration, and status. You receive this object when you create, send, or fetch an invoice.
The following examples show a simple and complex invoice object.
{
"id": "INV2-XXXX-XXXX-XXXX",
"status": "DRAFT",
"detail": {
"currency_code": "GBP",
"invoice_number": "INV-0001"
},
"invoicer": {
"email_address": "[email protected]"
},
"primary_recipients": [
{
"billing_info": {
"email_address": "[email protected]"
}
}
],
"items": [
{
"name": "Consulting",
"quantity": "1",
"unit_amount": {
"currency_code": "GBP",
"value": "100.00"
}
}
]
}{
"id": "INV2-XXXX-XXXX-XXXX-XXXX",
"detail": {
"invoice_number": "INV-2026-0089",
"reference": "SOW-2026-003",
"invoice_date": "2026-03-15",
"due_date": "2026-03-29",
"currency_code": "USD",
"note": "Thank you for working with us. Please don't hesitate to reach out with any questions.",
"memo": "Internal ref: Q1 closeout — Acct Manager: TJ — Client tier: Enterprise",
"term": "Payment due within 14 days of invoice date. Late payments subject to a 1.5% monthly fee.",
"payment_term": {
"term_type": "NET_14"
},
"metadata": {
"create_time": "2026-03-15T10:30:45Z",
"update_time": "2026-03-15T10:30:45Z",
"recipient_view_url": "https://www.paypal.com/invoice/view/...",
"first_sent_time": "2026-03-15T11:00:00Z"
}
},
"invoicer": {
"name": {
"given_name": "Taylor",
"surname": "Brooks"
},
"email_address": "[email protected]",
"business_name": "Brooks Design Studio",
"address": {
"address_line_1": "450 Market Street",
"address_line_2": "Suite 800",
"admin_area_2": "San Francisco",
"admin_area_1": "CA",
"postal_code": "94105",
"country_code": "US"
},
"phones": [
{
"country_code": "1",
"national_number": "4155550192",
"phone_type": "MOBILE"
}
],
"website": "https://brooksdesign.com"
},
"primary_recipients": [
{
"billing_info": {
"name": {
"given_name": "Jordan",
"surname": "Kim"
},
"business_name": "Kim & Associates LLC",
"email_address": "[email protected]",
"address": {
"address_line_1": "450 Market Street",
"address_line_2": "Suite 800",
"admin_area_2": "San Francisco",
"admin_area_1": "CA",
"postal_code": "94105",
"country_code": "US"
}
}
}
],
"items": [
{
"name": "UX Design — Discovery & Research",
"description": "User interviews, competitive analysis, journey mapping",
"quantity": "12",
"unit_amount": {
"currency_code": "USD",
"value": "150.00"
},
"unit_of_measure": "HOURS",
"tax": {
"name": "Sales Tax",
"percent": "8.5"
}
},
{
"name": "UX Design — Wireframing & Prototyping",
"description": "Low and high-fidelity wireframes, interactive prototype",
"quantity": "18",
"unit_amount": {
"currency_code": "USD",
"value": "150.00"
},
"unit_of_measure": "HOURS",
"tax": {
"name": "Sales Tax",
"percent": "8.5"
}
}
],
"configuration": {
"allow_tip": true,
"partial_payment": {
"allow_partial_payment": true,
"minimum_amount_due": {
"currency_code": "USD",
"value": "500.00"
}
},
"tax_calculated_after_discount": true,
"tax_inclusive": false
},
"amount": {
"breakdown": {
"items_total": {
"currency_code": "USD",
"value": "4500.00"
},
"tax_total": {
"currency_code": "USD",
"value": "382.50"
}
},
"total_amount": {
"currency_code": "USD",
"value": "4882.50"
}
},
"status": "SENT",
"payment_summary": {
"paid_amount": {
"currency_code": "USD",
"value": "0.00"
},
"outstanding_balance": {
"currency_code": "USD",
"value": "4882.50"
}
}
}The following tables document the top-level fields in the invoice object, along with the fields in each nested object.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Read-only | The unique PayPal-generated invoice ID (INV2-XXXX-XXXX-XXXX-XXXX). |
status | string | Read-only | The current status of the invoice. Values: DRAFT, SENT, SCHEDULED, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_PAID, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED, UNPAID, PAYMENT_PENDING. |
detail | object | Required | Core invoice details including invoice number, date, currency, and payment terms. See detail for more information. |
invoicer | object | Optional | The business information of the invoice sender. See invoicer for more information. |
primary_recipients | array | Optional | The billing and shipping information for the invoice recipients. Up to 100 recipients. See primary_recipients for more information. |
additional_recipients | array | Optional | An array of CC email addresses to receive invoice notifications. Up to 100 addresses. |
items | array | Optional | The line items on the invoice. Up to 100 items. See items for more information. |
configuration | object | Optional | Invoice configuration options including partial payment, tips, and tax settings. See configuration for more information. |
amount | object | Read-only | The computed invoice amount summary including totals, tax, discounts, and shipping. See amount for more information. |
due_amount | object | Read-only | The amount outstanding on the invoice. Contains currency_code and value. |
gratuity | object | Read-only | The tip amount added by the payer. Contains currency_code and value. |
payments | object | Read-only | Payments recorded against the invoice. See payments for more information. |
refunds | object | Read-only | Refunds recorded against the invoice. See refunds for more information. |
links | array | Read-only | HATEOAS links for available actions on the invoice, for example, send, replace, delete, qr-code. |
This is core invoice metadata that is required when creating an invoice.
| Field | Type | Required | Description |
|---|---|---|---|
invoice_number | string | Optional | A merchant-defined invoice number. Max 25 characters. If omitted, PayPal auto-generates one. |
invoice_date | string | Optional | The invoice date in YYYY-MM-DD format. Defaults to the date the invoice is created. |
currency_code | string | Required | The three-character ISO-4217 currency code, for example, USD, GBP. |
reference | string | Optional | A merchant-defined reference identifier, for example, a purchase order number. Max 120 characters. |
payment_term | object | Optional | The payment due terms. Contains term_type, for example, NET_10, NET_30, DUE_ON_DATE_SPECIFIED, and due_date. |
note | string | Optional | A note to the recipient. Visible on the invoice. Max 4,000 characters. |
terms_and_conditions | string | Optional | The terms and conditions of the invoice. Max 4,000 characters. |
memo | string | Optional | A memo for internal use. Not visible to the recipient. Max 500 characters. |
attachments | array | Optional | File references to attach to the invoice. |
metadata | object | Read-only | Audit data including create_time, last_update_time, recipient_view_url, and invoicer_view_url. |
The sender's business information displayed on the invoice.
| Field | Type | Required | Description |
|---|---|---|---|
email_address | string | Optional | The invoicer's email address. Must match the email of the PayPal business account associated with the access token. |
name | object | Optional | The invoicer's name. Contains given_name and surname. |
address | object | Optional | The invoicer's address. Contains address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code. |
phones | array | Optional | The invoicer's phone numbers. Each entry contains country_code, national_number, and phone_type, for example, MOBILE, HOME, WORK. |
website | string | Optional | The invoicer's website URL. Max 2,048 characters. |
tax_id | string | Optional | The invoicer's tax ID. |
logo_url | string | Optional | The URL of a logo to display on the invoice. Must be HTTPS. Max 2,000 characters. |
additional_notes | string | Optional | Additional notes about the invoicer. Max 40 characters. |
An array of recipient objects. Each entry contains a billing_info object and optionally a shipping_info object.
| Field | Type | Required | Description |
|---|---|---|---|
email_address | string | Optional | The recipient's email address. PayPal sends the invoice notification to this address. |
name | object | Optional | The recipient's name. Contains given_name and surname. |
address | object | Optional | The recipient's billing address. Same structure as invoicer.address. |
phones | array | Optional | The recipient's phone numbers. Same structure as invoicer.phones. |
additional_info_value | string | Optional | A free-text field for additional recipient information, for example, account number. Max 40 characters. |
| Field | Type | Required | Description |
|---|---|---|---|
name | object | Optional | The recipient's name for shipping. Contains given_name and surname. |
address | object | Optional | The shipping destination address. Same structure as invoicer.address. |
An array of line items on the invoice. Each item contains the following fields.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | The item name. Max 200 characters. |
description | string | Optional | A description of the item. Max 1,000 characters. |
quantity | string | Required | The quantity of the item. Supports decimals, for example, "2.5". |
unit_amount | object | Required | The price per unit. Contains currency_code and value. |
tax | object | Optional | Tax applied to this item. Contains name, percent, and a computed amount. |
discount | object | Optional | Discount applied to this item. Contains either percent or a fixed amount. |
item_date | string | Optional | The date the item or service was provided. Format: YYYY-MM-DD. |
unit_of_measure | string | Optional | The unit of measure for the item. Values: QUANTITY, HOURS, AMOUNT. |
Options that control invoice behavior and payment rules.
| Field | Type | Required | Description |
|---|---|---|---|
partial_payment | object | Optional | Partial payment settings. Contains allow_partial_payment and minimum_amount_due. |
allow_tip | boolean | Optional | If true, the payer can add a tip when paying. Default: false. |
tax_calculated_after_discount | boolean | Optional | If true, tax is calculated on the post-discount amount. Default: false. |
tax_inclusive | boolean | Optional | If true, the unit amounts already include tax. Default: false. |
template_id | string | Optional | The ID of a saved template to associate with this invoice. Doesn't auto-populate template data. |
A read-only computed summary of the invoice total. PayPal populates this based on items and configuration.
| Field | Type | Description |
|---|---|---|
currency_code | string | The invoice currency. |
value | string | The total invoice amount. |
breakdown | object | A detailed breakdown of the total. |
breakdown.item_total | object | The subtotal of all line items before tax or discount. |
breakdown.discount | object | The total discount applied. Contains item_discount and invoice_discount. |
breakdown.tax_total | object | The total tax applied across all items and shipping. |
breakdown.shipping | object | The shipping amount and any associated tax. |
breakdown.custom | object | A custom line item, for example, packing charges. Contains label and amount. |
A read-only record of payments made against the invoice.
| Field | Type | Description |
|---|---|---|
paid_amount | object | The total amount paid so far. Contains currency_code and value. |
transactions | array | An array of individual payment records. Each contains payment_id, method, payment_date, note, and amount. |
A read-only record of refunds issued against the invoice.
| Field | Type | Description |
|---|---|---|
refund_amount | object | The total amount refunded so far. Contains currency_code and value. |
transactions | array | An array of individual refund records. Each contains refund_id, method, refund_date, and amount. |