openapi: 3.0.3
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:
file_reference:
type: object
title: File Reference
description: The file reference. Can be a file in PayPal MediaServ, PayPal DMS, or other custom store.
properties:
id:
type: string
description: The ID of the referenced file.
minLength: 1
maxLength: 255
reference_url:
type: string
description: The reference URL for the file.
format: uri
minLength: 1
maxLength: 2000
content_type:
type: string
description: The [Internet Assigned Numbers Authority (IANA) media type of the file](https://www.iana.org/assignments/media-types/media-types.xhtml).
create_time:
$ref: '#/components/schemas/date_time'
description: The date and time when the file was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
size:
type: string
description: The size of the file, in bytes.
pattern: ^[0-9]+$
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
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'
payments:
type: object
title: Payments
description: An array of payments registered against the invoice.
properties:
paid_amount:
$ref: '#/components/schemas/money'
readOnly: true
description: The aggregated payment amounts against this invoice.
transactions:
type: array
description: An array of payment details for the invoice. The payment details of the invoice like payment type, method, date, discount and transaction type.
maxItems: 100
items:
$ref: '#/components/schemas/payment_detail'
readOnly: true
language:
type: string
description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/).
format: ppaas_common_language_v3
maxLength: 10
minLength: 2
pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
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_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
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
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
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
date_no_time:
type: string
description: The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
format: ppaas_date_notime_v2
minLength: 10
maxLength: 10
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$
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
aggregated_discount:
type: object
title: Aggregated Discount
description: The discount. Can be an item- or invoice-level discount, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent.
properties:
invoice_discount:
$ref: '#/components/schemas/discount'
description: The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
item_discount:
$ref: '#/components/schemas/money'
description: The discount as a percent or amount at item level. The item discount amount is subtracted from each item amount.
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
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_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
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_422:
type: object
title: Unprocessable Entity Error
description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
properties:
name:
type: string
enum:
- UNPROCESSABLE_ENTITY
message:
type: string
enum:
- The requested action could not be performed, semantically incorrect, or failed business validation.
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'
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
name:
type: object
title: Name
description: The name of the party.
properties:
prefix:
type: string
description: The prefix, or title, to the party's name.
maxLength: 140
given_name:
type: string
description: When the party is a person, the party's given, or first, name.
maxLength: 140
surname:
type: string
description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
maxLength: 140
middle_name:
type: string
description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
maxLength: 140
suffix:
type: string
description: The suffix for the party's name.
maxLength: 140
alternate_full_name:
type: string
description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
maxLength: 300
full_name:
type: string
description: When the party is a person, the party's full name.
maxLength: 300
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'
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.
phone_detail:
type: object
title: Phone Detail
description: The phone details. Includes the phone number and type.
required:
- phone_type
allOf:
- $ref: '#/components/schemas/phone'
- properties:
phone_type:
$ref: '#/components/schemas/phone_type'
refunds:
type: object
title: Refunds
description: The invoicing refund details. Includes the refund type, date, amount, and method.
properties:
refund_amount:
$ref: '#/components/schemas/money'
readOnly: true
description: The aggregated refund amounts.
transactions:
type: array
description: An array of refund details for the invoice. Includes the refund type, date, amount, and method.
maxItems: 100
items:
$ref: '#/components/schemas/refund_detail'
readOnly: true
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 must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 3
pattern: ^[0-9]{1,3}?$
national_number:
type: string
description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 14
pattern: ^[0-9]{1,14}?$
extension_number:
type: string
description: The extension number.
minLength: 1
maxLength: 15
pattern: ^[0-9]{1,15}?$
required:
- country_code
- national_number
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
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*.
amount_summary_detail:
type: object
title: Invoice Amount Summary
description: The invoice amount summary of item total, discount, tax total, and shipping.
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]+))$
breakdown:
$ref: '#/components/schemas/amount_with_breakdown'
description: The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, custom amount, shipping and discounts, if any.
template_metadata:
type: object
title: Template Metadata
description: The audit metadata. Captures all template actions on create and update.
properties:
create_time:
$ref: '#/components/schemas/date_time'
description: The date and time when the resource was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
created_by:
type: string
description: The email address of the account that created the resource.
readOnly: true
last_update_time:
$ref: '#/components/schemas/date_time'
description: The date and time when the resource was last edited, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
last_updated_by:
type: string
description: The email address of the account that last edited the resource.
readOnly: true
recipient_info:
type: object
title: Recipient Information
description: The billing and shipping information. Includes name, email, address, phone, and language.
properties:
billing_info:
$ref: '#/components/schemas/billing_info'
description: The billing information for the invoice recipient. Includes name, address, email, phone, and language.
shipping_info:
$ref: '#/components/schemas/contact_name_address'
# --- 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