> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Invoice object 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. ## Sample invoice objects The following examples show a simple and complex invoice object. ### Simple ```json [expandable] theme={null} { "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 ```json [expandable] theme={null} { "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**](#detail) for more information. | | `invoicer` | object | Optional | The business information of the invoice sender. See [**invoicer**](#invoicer) for more information. | | `primary_recipients` | array | Optional | The billing and shipping information for the invoice recipients. Up to 100 recipients. See [**primary\_recipients**](#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**](#items) for more information. | | `configuration` | object | Optional | Invoice configuration options including partial payment, tips, and tax settings. See [**configuration**](#configuration) for more information. | | `amount` | object | Read-only | The computed invoice amount summary including totals, tax, discounts, and shipping. See [**amount**](#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**](#payments) for more information. | | `refunds` | object | Read-only | Refunds recorded against the invoice. See [**refunds**](#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 a `billing_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`. | Create and send your first invoice using the PayPal Invoicing API. Explore the full schema definitions and interactive examples for the PayPal Invoicing API.