Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Paypal Subscriptions Authorizations Search Invoices API
description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
version: '1.6'
contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
description: PayPal Live Environment
tags:
- name: Search-Invoices
description: Use the `/search-invoices` resource to search for and list invoices that match search criteria.
paths:
/v2/invoicing/search-invoices:
post:
summary: Paypal Search for invoices
description: Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.
operationId: invoices.search-invoices
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists the invoices that match the search criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/invoices'
multipart/mixed:
schema:
$ref: '#/components/schemas/invoices'
'400':
description: Invalid request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/invoices.search-invoices-400'
multipart/mixed:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/invoices.search-invoices-400'
'403':
description: Authorization Error.
content:
application/json:
schema:
$ref: '#/components/schemas/error_403'
multipart/mixed:
schema:
$ref: '#/components/schemas/error_403'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/total_required'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search_data'
examples:
'0':
$ref: '#/components/examples/search_data'
description: The invoice search can be used to retrieve the invoices based on the search parameters.
security:
- Oauth2:
- https://uri.paypal.com/services/invoicing/invoices/read
tags:
- Search-Invoices
components:
schemas:
invoice:
type: object
title: Invoice
description: The invoice details which includes all information of the invoice like items, billing information.
required:
- detail
properties:
id:
type: string
description: The ID of the invoice.
readOnly: true
maxLength: 30
parent_id:
type: string
description: The parent ID to an invoice that defines the group invoice to which the invoice is related.
readOnly: true
maxLength: 30
status:
$ref: '#/components/schemas/invoice_status'
readOnly: true
detail:
$ref: '#/components/schemas/invoice_detail'
description: The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.
invoicer:
$ref: '#/components/schemas/invoicer_info'
description: The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.
primary_recipients:
type: array
items:
$ref: '#/components/schemas/recipient_info'
maxItems: 100
description: The billing and shipping information. Includes name, email, address, phone and language.
additional_recipients:
type: array
maxItems: 100
description: 'An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.<blockquote><strong>Note:</strong> Valid values are email addresses in the `additional_recipients` value associated with the invoice.</blockquote>'
items:
$ref: '#/components/schemas/email_address'
items:
type: array
description: An array of invoice line item information.
maxItems: 100
items:
$ref: '#/components/schemas/item'
configuration:
$ref: '#/components/schemas/configuration'
description: The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
amount:
$ref: '#/components/schemas/amount_summary_detail'
description: The invoice amount summary of item total, discount, tax total and shipping..
due_amount:
description: The due amount, which is the balance amount outstanding after payments.
$ref: '#/components/schemas/money'
readOnly: true
gratuity:
description: The amount paid by the payer as gratuity to the invoicer.
$ref: '#/components/schemas/money'
readOnly: true
payments:
$ref: '#/components/schemas/payments'
description: List of payments registered against the invoice..
refunds:
$ref: '#/components/schemas/refunds'
description: List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description'
link_description:
type: object
title: Link Description
description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
required:
- href
- rel
properties:
href:
type: string
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel:
type: string
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
method:
type: string
description: The HTTP method required to make the related call.
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
invoice_creation_flow:
type: string
title: Invoice Creation Flow
description: The frequency at which the invoice is sent:<ul><li>Multiple recipient. Sent to multiple recipients.</li><li>Batch. Sent in a batch.</li><li>Regular single. Sent one time to a single recipient.</li></ul>
enum:
- MULTIPLE_RECIPIENTS_GROUP
- BATCH
- REGULAR_SINGLE
money:
type: object
title: Money
description: The currency and amount for a financial transaction, such as a balance or payment due.
properties:
currency_code:
$ref: '#/components/schemas/currency_code'
value:
type: string
description: The value, which might be:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/).
maxLength: 32
pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
required:
- currency_code
- value
custom_amount:
type: object
title: Custom Amount
description: The custom amount to apply to an invoice. If you include a label, you must include a custom amount.
required:
- label
properties:
label:
type: string
description: The label to the custom amount of the invoice.
maxLength: 50
amount:
$ref: '#/components/schemas/money'
description: The custom amount value. Value is from `-1000000` to `1000000`. Supports up to two decimal places.
date_time:
type: string
description: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
format: ppaas_date_time_v3
minLength: 20
maxLength: 64
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$
unit_of_measure:
type: string
description: The unit of measure for the invoiced item.
enum:
- QUANTITY
- HOURS
- AMOUNT
currency_code:
description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.
type: string
format: ppaas_common_currency_code_v2
minLength: 3
maxLength: 3
search_data:
type: object
title: Search Data
description: The invoice search parameters.
properties:
recipient_email:
type: string
maxLength: 254
description: Filters the search by the email address.
recipient_first_name:
type: string
description: Filters the search by the recipient first name.
maxLength: 140
recipient_last_name:
type: string
description: Filters the search by the recipient last name.
maxLength: 140
recipient_business_name:
type: string
description: Filters the search by the recipient business name.
maxLength: 300
invoice_number:
type: string
maxLength: 25
description: Filters the search by the invoice number.
status:
type: array
description: An array of status values.
items:
$ref: '#/components/schemas/invoice_status'
maxItems: 5
reference:
type: string
description: The reference data, such as a PO number.
maxLength: 120
currency_code:
$ref: '#/components/schemas/currency_code'
description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.
memo:
type: string
description: A private bookkeeping memo for the user.
maxLength: 500
total_amount_range:
$ref: '#/components/schemas/amount_range'
description: Filters the search by the total amount.
invoice_date_range:
$ref: '#/components/schemas/date_range'
description: Filters the search by a date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
due_date_range:
$ref: '#/components/schemas/date_range'
description: Filters the search by a due date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
payment_date_range:
$ref: '#/components/schemas/date_time_range'
creation_date_range:
$ref: '#/components/schemas/date_time_range'
description: Filters the search by a creation date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
archived:
type: boolean
description: Indicates whether to list merchant-archived invoices in the response. Value is:<ul><li><code>true</code>. Response lists only merchant-archived invoices.</li><li><code>false</code>. Response lists only unarchived invoices.</li><li><code>null</code>. Response lists all invoices.</li></ul>
fields:
description: A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are <code>items</code>, <code>payments</code>, <code>refunds</code>, <code>additional_recipients_info</code>, and <code>attachments</code>.
type: array
items:
type: string
description: The name of the field.
error_500:
type: object
title: Internal Server Error
description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
properties:
name:
type: string
enum:
- INTERNAL_SERVER_ERROR
message:
type: string
enum:
- An internal server error occurred.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
example:
name: INTERNAL_SERVER_ERROR
message: An internal server error occurred.
debug_id: 90957fca61718
links:
- href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR
rel: information_link
amount_with_breakdown:
type: object
title: Amount with Breakdown
description: The breakdown of the amount. Includes total item amount, total tax amount, custom amount, and shipping and discounts, if any.
properties:
item_total:
$ref: '#/components/schemas/money'
description: The subtotal for all items. Must equal the sum of (`items[].unit_amount` * `items[].quantity`) for all items.
discount:
$ref: '#/components/schemas/aggregated_discount'
description: The discount can be at the item or invoice level, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent.
tax_total:
$ref: '#/components/schemas/money'
description: The aggregated amount of the item and shipping taxes.
shipping:
$ref: '#/components/schemas/shipping_cost'
description: The shipping fee for all items. Includes tax on shipping.
custom:
$ref: '#/components/schemas/custom_amount'
description: The custom amount to apply to an invoice. If you include a label, you must include the custom amount.
item:
type: object
title: Invoice Item
description: An array of invoice line item information. The maximum items for an invoice is `100`.
properties:
id:
type: string
description: The ID of the invoice line item.
readOnly: true
maxLength: 22
name:
type: string
description: The item name for the invoice line item.
maxLength: 200
description:
type: string
description: The item description for the invoice line item.
maxLength: 1000
quantity:
type: string
maxLength: 14
minLength: 0
description: The quantity of the item that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places.
unit_amount:
$ref: '#/components/schemas/money'
description: The unit price of the item. This does not include tax and discount. Value is from `-1000000` to `1000000`. Supports up to two decimal places.
tax:
$ref: '#/components/schemas/tax'
description: The tax associated with the item. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places.
item_date:
$ref: '#/components/schemas/date_no_time'
description: The date when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*.
discount:
$ref: '#/components/schemas/discount'
description: Discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
unit_of_measure:
description: The unit of measure for the invoiced item. For `AMOUNT` the `unit_amount` and `quantity` are not shown on the invoice.<blockquote><strong>Note:</strong> If your specify different `unit_of_measure` values for the same invoice, the invoice uses the first value.</blockquote>
$ref: '#/components/schemas/unit_of_measure'
required:
- name
- quantity
- unit_amount
payment_term:
type: object
title: Payment Term
description: The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days.
properties:
term_type:
description: The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
$ref: '#/components/schemas/payment_term_type'
phone_type:
type: string
title: Phone Type
description: The phone type.
enum:
- FAX
- HOME
- MOBILE
- OTHER
- PAGER
partial_payment:
type: object
title: Partial Payment
description: The partial payment details. Includes the minimum amount that the invoicer expects from the payer.
properties:
allow_partial_payment:
type: boolean
description: Indicates whether the invoice allows a partial payment. If `false`, the invoice must be paid in full. If `true`, the invoice allows partial payments.<blockquote><strong>Note:</strong> This feature is not available for users in `India`, `Brazil`, or `Israel`.</blockquote>
default: false
minimum_amount_due:
$ref: '#/components/schemas/money'
description: The minimum amount allowed for a partial payment. Valid only when `allow_partial_payment` is `true`.
error_400:
type: object
title: Bad Request Error
description: Request is not well-formed, syntactically incorrect, or violates schema.
properties:
name:
type: string
enum:
- INVALID_REQUEST
message:
type: string
enum:
- Request is not well-formed, syntactically incorrect, or violates schema.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
invoice_detail:
type: object
title: Invoice Detail
description: The details of the invoice. Includes invoice number, date, payment terms, and audit metadata.
allOf:
- $ref: '#/components/schemas/detail'
- properties:
invoice_number:
type: string
description: The invoice number. Default is the number that is auto-incremented number from the last number.
maxLength: 127
invoice_date:
$ref: '#/components/schemas/date_no_time'
description: The invoice date as specificed by the sender, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Only UTC is supported in response. For example, *yyyy*-*MM*-*dd*T*z*.
payment_term:
$ref: '#/components/schemas/invoice_payment_term'
description: The payment due date for the invoice. Value is either but not both <code>term_type</code> or <code>due_date</code>.
metadata:
$ref: '#/components/schemas/metadata'
description: The audit metadata. Captures all invoicing actions on create, send, update, and cancel.
readOnly: true
invoice_status:
type: string
title: Invoice Status
description: The status of the invoice.
enum:
- DRAFT
- SENT
- SCHEDULED
- PAID
- MARKED_AS_PAID
- CANCELLED
- REFUNDED
- PARTIALLY_PAID
- PARTIALLY_REFUNDED
- MARKED_AS_REFUNDED
- UNPAID
- PAYMENT_PENDING
detail:
title: Invoice_Detail
description: The details of the invoice like notes, terms and conditions, memo, attachments.
required:
- currency_code
properties:
reference:
type: string
description: The reference data. Includes a post office (PO) number.
maxLength: 120
currency_code:
$ref: '#/components/schemas/currency_code'
description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.
note:
type: string
description: A note to the invoice recipient. Also appears on the invoice notification email.
maxLength: 4000
terms_and_conditions:
type: string
description: The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.
maxLength: 4000
memo:
type: string
description: A private bookkeeping memo for the user.
maxLength: 500
attachments:
type: array
description: An array of PayPal IDs for the files that are attached to an invoice.
maximum: 5
items:
$ref: '#/components/schemas/file_reference'
business_name:
type: object
title: Business Name
description: The business name of the party.
properties:
business_name:
type: string
description: Required. The business name of the party.
maxLength: 300
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value:
type: string
description: The value of the field that caused the error.
location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
default: body
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
required:
- issue
metadata:
type: object
title: Metadata
description: The audit metadata. Captures all invoicing actions on create, send, update, and cancel.
allOf:
- $ref: '#/components/schemas/template_metadata'
- properties:
cancel_time:
$ref: '#/components/schemas/date_time'
description: The date and time when the resource was canceled, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
cancelled_by:
type: string
description: The actor who canceled the resource.
readOnly: true
first_sent_time:
$ref: '#/components/schemas/date_time'
description: The date and time when the resource was first sent, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
last_sent_time:
$ref: '#/components/schemas/date_time'
description: The date and time when the resource was last sent, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
last_sent_by:
type: string
description: The email address of the account that last sent the resource.
readOnly: true
created_by_flow:
description: The flow variation that created this invoice.
$ref: '#/components/schemas/invoice_creation_flow'
readOnly: true
recipient_view_url:
type: string
readOnly: true
format: uri
description: The URL for the invoice payer view hosted on paypal.com.
invoicer_view_url:
type: string
readOnly: true
format: uri
description: The URL for the invoice merchant view hosted on paypal.com.
payment_term_type:
type: string
title: Payment Term Type
description: The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
enum:
- DUE_ON_RECEIPT
- DUE_ON_DATE_SPECIFIED
- NET_10
- NET_15
- NET_30
- NET_45
- NET_60
- NET_90
- NO_DUE_DATE
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
type: string
minLength: 0
maxLength: 20000
pattern: ^.*$
rel:
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
type: string
minLength: 0
maxLength: 100
pattern: ^.*$
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 7
pattern: ^[A-Z]*$
enum:
- CONNECT
- DELETE
- GET
- HEAD
- OPTIONS
- PATCH
- POST
- PUT
invoices.search-invoices-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_INTEGER_MAX_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MAX_VALUE
description:
type: string
enum:
- Value exceeds max value.
- title: INVALID_INTEGER_MIN_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MIN_VALUE
description:
type: string
enum:
- Value less than minimum value.
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- the value of a field is too long.
- title: INVALID_ARRAY_MAX_ITEMS
properties:
issue:
type: string
enum:
- INVALID_ARRAY_MAX_ITEMS
description:
type: string
enum:
- the number of items in an array parameter is too large.
- title: INVALID_STRING_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_LENGTH
description:
type: string
enum:
- the value of a field is either too short or too long.
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- the value of a field is too long.
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- the value of a field does not conform to the expected format.
error_401:
type: object
title: Unauthorized Error
description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
properties:
name:
type: string
enum:
- AUTHENTICATION_FAILURE
message:
type: string
enum:
- Authentication failed due to missing authorization header, or invalid authentication credentials.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
invoice_payment_term:
type: object
title: Invoice Payment Term
description: The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days.
allOf:
- $ref: '#/components/schemas/payment_term'
- properties:
due_date:
$ref: '#/components/schemas/date_no_time'
description: The date when the invoice payment is due, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*.
phone:
type: object
title: Phone
description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
properties:
country_code:
type: string
description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-search-invoices-api-openapi.yml