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.
Sample invoice objects
The following examples show a simple and complex invoice object.Simple
{
"id": "INV2-XXXX-XXXX-XXXX",
"status": "DRAFT",
"detail": {
"currency_code": "GBP",
"invoice_number": "INV-0001"
},
"invoicer": {
"email_address": "merchant@example.com"
},
"primary_recipients": [
{
"billing_info": {
"email_address": "customer@example.com"
}
}
],
"items": [
{
"name": "Consulting",
"quantity": "1",
"unit_amount": {
"currency_code": "GBP",
"value": "100.00"
}
}
]
}
Complex
{
"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": "taylor@brooksdesign.com",
"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": "jordan@kimassociates.com",
"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"
}
}
}
Object schema
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. |
detail
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. |
invoicer
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. |
primary_recipients
An array of recipient objects. Each entry contains abilling_info object and optionally a shipping_info object.
billing_info
| 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. |
shipping_info
| 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. |
items
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. |
configuration
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. |
amount
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. |
payments
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. |
refunds
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. |
Quick start using Invoicing API
Create and send your first invoice using the PayPal Invoicing API.
Reference
Explore the full schema definitions and interactive examples for the PayPal Invoicing API.