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

{
  "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 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`.

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.

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

Sample invoice objects

Simple

Complex

Object schema

detail

invoicer

primary_recipients

billing_info

shipping_info

items

configuration

amount

payments

refunds

Quick start using Invoicing API

Reference

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

​Sample invoice objects

​Simple

​Complex

​Object schema

​detail

​invoicer

​primary_recipients

​billing_info

​shipping_info

​items

​configuration

​amount

​payments

​refunds

Quick start using Invoicing API

Reference

Sample invoice objects

Simple

Complex

Object schema

detail

invoicer

primary_recipients

billing_info

shipping_info

items

configuration

amount

payments

refunds