Skip to main content
POST
/
v2
/
invoicing
/
search-invoices
Search for invoices
curl --request POST \
  --url https://api-m.sandbox.paypal.com/v2/invoicing/search-invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipient_email": "<string>",
  "recipient_first_name": "<string>",
  "recipient_last_name": "<string>",
  "recipient_business_name": "<string>",
  "invoice_number": "<string>",
  "status": [
    "DRAFT"
  ],
  "reference": "<string>",
  "currency_code": "<string>",
  "memo": "<string>",
  "total_amount_range": {
    "lower_amount": {
      "currency_code": "<string>",
      "value": "<string>"
    },
    "upper_amount": {
      "currency_code": "<string>",
      "value": "<string>"
    }
  },
  "invoice_date_range": {
    "start": "<string>",
    "end": "<string>"
  },
  "due_date_range": {
    "start": "<string>",
    "end": "<string>"
  },
  "payment_date_range": {
    "start": "<string>",
    "end": "<string>"
  },
  "creation_date_range": {
    "start": "<string>",
    "end": "<string>"
  },
  "archived": true,
  "fields": [
    "<string>"
  ]
}
'
{
  "total_pages": 1073741823,
  "total_items": 1073741823,
  "items": [
    {
      "detail": {
        "currency_code": "<string>",
        "reference": "<string>",
        "note": "<string>",
        "terms_and_conditions": "<string>",
        "memo": "<string>",
        "attachments": [
          {
            "id": "<string>",
            "reference_url": "<string>",
            "content_type": "<string>",
            "create_time": "<string>",
            "size": "<string>"
          }
        ],
        "invoice_number": "<string>",
        "invoice_date": "<string>",
        "payment_term": {
          "term_type": "DUE_ON_RECEIPT",
          "due_date": "<string>"
        },
        "metadata": {
          "create_time": "<string>",
          "created_by": "<string>",
          "last_update_time": "<string>",
          "last_updated_by": "<string>",
          "cancel_time": "<string>",
          "cancelled_by": "<string>",
          "first_sent_time": "<string>",
          "last_sent_time": "<string>",
          "last_sent_by": "<string>",
          "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP",
          "recipient_view_url": "<string>",
          "invoicer_view_url": "<string>"
        }
      },
      "id": "<string>",
      "parent_id": "<string>",
      "status": "DRAFT",
      "invoicer": {
        "business_name": "<string>",
        "name": {
          "prefix": "<string>",
          "given_name": "<string>",
          "surname": "<string>",
          "middle_name": "<string>",
          "suffix": "<string>",
          "alternate_full_name": "<string>",
          "full_name": "<string>"
        },
        "address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "address_line_3": "<string>",
          "admin_area_4": "<string>",
          "admin_area_3": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>",
          "address_details": {
            "street_number": "<string>",
            "street_name": "<string>",
            "street_type": "<string>",
            "delivery_service": "<string>",
            "building_name": "<string>",
            "sub_building": "<string>"
          }
        },
        "email_address": "<string>",
        "phones": [
          {
            "country_code": "<string>",
            "national_number": "<string>",
            "phone_type": "FAX",
            "extension_number": "<string>"
          }
        ],
        "website": "<string>",
        "tax_id": "<string>",
        "additional_notes": "<string>",
        "logo_url": "<string>"
      },
      "primary_recipients": [
        {
          "billing_info": {
            "business_name": "<string>",
            "name": {
              "prefix": "<string>",
              "given_name": "<string>",
              "surname": "<string>",
              "middle_name": "<string>",
              "suffix": "<string>",
              "alternate_full_name": "<string>",
              "full_name": "<string>"
            },
            "address": {
              "country_code": "<string>",
              "address_line_1": "<string>",
              "address_line_2": "<string>",
              "address_line_3": "<string>",
              "admin_area_4": "<string>",
              "admin_area_3": "<string>",
              "admin_area_2": "<string>",
              "admin_area_1": "<string>",
              "postal_code": "<string>",
              "address_details": {
                "street_number": "<string>",
                "street_name": "<string>",
                "street_type": "<string>",
                "delivery_service": "<string>",
                "building_name": "<string>",
                "sub_building": "<string>"
              }
            },
            "email_address": "<string>",
            "phones": [
              {
                "country_code": "<string>",
                "national_number": "<string>",
                "phone_type": "FAX",
                "extension_number": "<string>"
              }
            ],
            "additional_info": "<string>",
            "language": "<string>"
          },
          "shipping_info": {
            "business_name": "<string>",
            "name": {
              "prefix": "<string>",
              "given_name": "<string>",
              "surname": "<string>",
              "middle_name": "<string>",
              "suffix": "<string>",
              "alternate_full_name": "<string>",
              "full_name": "<string>"
            },
            "address": {
              "country_code": "<string>",
              "address_line_1": "<string>",
              "address_line_2": "<string>",
              "address_line_3": "<string>",
              "admin_area_4": "<string>",
              "admin_area_3": "<string>",
              "admin_area_2": "<string>",
              "admin_area_1": "<string>",
              "postal_code": "<string>",
              "address_details": {
                "street_number": "<string>",
                "street_name": "<string>",
                "street_type": "<string>",
                "delivery_service": "<string>",
                "building_name": "<string>",
                "sub_building": "<string>"
              }
            }
          }
        }
      ],
      "additional_recipients": [
        "<string>"
      ],
      "items": [
        {
          "name": "<string>",
          "quantity": "<string>",
          "unit_amount": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "id": "<string>",
          "description": "<string>",
          "tax": {
            "name": "<string>",
            "percent": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "tax_note": "<string>"
          },
          "item_date": "<string>",
          "discount": {
            "percent": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          },
          "unit_of_measure": "QUANTITY"
        }
      ],
      "configuration": {
        "tax_calculated_after_discount": true,
        "tax_inclusive": false,
        "allow_tip": false,
        "partial_payment": {
          "allow_partial_payment": false,
          "minimum_amount_due": {
            "currency_code": "<string>",
            "value": "<string>"
          }
        },
        "has_conditional_rule": false,
        "template_id": "PayPal system template"
      },
      "amount": {
        "currency_code": "<string>",
        "value": "<string>",
        "breakdown": {
          "item_total": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "discount": {
            "invoice_discount": {
              "percent": "<string>",
              "amount": {
                "currency_code": "<string>",
                "value": "<string>"
              }
            },
            "item_discount": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          },
          "tax_total": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "shipping": {
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "tax": {
              "name": "<string>",
              "percent": "<string>",
              "amount": {
                "currency_code": "<string>",
                "value": "<string>"
              },
              "tax_note": "<string>"
            }
          },
          "custom": {
            "label": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          }
        }
      },
      "due_amount": {
        "currency_code": "<string>",
        "value": "<string>"
      },
      "gratuity": {
        "currency_code": "<string>",
        "value": "<string>"
      },
      "payments": {
        "paid_amount": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "transactions": [
          {
            "method": "BANK_TRANSFER",
            "type": "PAYPAL",
            "payment_id": "<string>",
            "payment_date": "<string>",
            "payment_date_time": "<string>",
            "note": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "shipping_info": {
              "business_name": "<string>",
              "name": {
                "prefix": "<string>",
                "given_name": "<string>",
                "surname": "<string>",
                "middle_name": "<string>",
                "suffix": "<string>",
                "alternate_full_name": "<string>",
                "full_name": "<string>"
              },
              "address": {
                "country_code": "<string>",
                "address_line_1": "<string>",
                "address_line_2": "<string>",
                "address_line_3": "<string>",
                "admin_area_4": "<string>",
                "admin_area_3": "<string>",
                "admin_area_2": "<string>",
                "admin_area_1": "<string>",
                "postal_code": "<string>",
                "address_details": {
                  "street_number": "<string>",
                  "street_name": "<string>",
                  "street_type": "<string>",
                  "delivery_service": "<string>",
                  "building_name": "<string>",
                  "sub_building": "<string>"
                }
              }
            }
          }
        ]
      },
      "refunds": {
        "refund_amount": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "transactions": [
          {
            "method": "BANK_TRANSFER",
            "type": "PAYPAL",
            "refund_id": "<string>",
            "refund_date": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          }
        ]
      },
      "links": [
        {
          "href": "<string>",
          "rel": "<string>",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "<string>",
      "rel": "<string>",
      "method": "GET"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Oauth 2.0 authentication

Query Parameters

​
page
integer
default:1

The page number to be retrieved, for the list of templates. So, a combination of page=1 and page_size=20 returns the first 20 templates. A combination of page=2 and page_size=20 returns the next 20 templates.

Required range: 1 <= x <= 1000
​
page_size
integer
default:20

The maximum number of templates to return in the response.

Required range: 1 <= x <= 100
​
total_required
boolean
default:false

Indicates whether the to show total_pages and total_items in the response.

Body

application/json

The invoice search can be used to retrieve the invoices based on the search parameters.

The invoice search parameters.

​
recipient_email
string

Filters the search by the email address.

Maximum string length: 254
​
recipient_first_name
string

Filters the search by the recipient first name.

Maximum string length: 140
​
recipient_last_name
string

Filters the search by the recipient last name.

Maximum string length: 140
​
recipient_business_name
string

Filters the search by the recipient business name.

Maximum string length: 300
​
invoice_number
string

Filters the search by the invoice number.

Maximum string length: 25
​
status
enum<string>[]

An array of status values.

Maximum array length: 5

The status of the invoice.

Available options:
DRAFT,
SENT,
SCHEDULED,
PAID,
MARKED_AS_PAID,
CANCELLED,
REFUNDED,
PARTIALLY_PAID,
PARTIALLY_REFUNDED,
MARKED_AS_REFUNDED,
UNPAID,
PAYMENT_PENDING,
AUTO_CANCELLED,
PAID_EXTERNAL,
REFUNDED_EXTERNAL,
SHARED
Maximum string length: 255
​
reference
string

The reference data. Includes a Purchase Order (PO) number.

Maximum string length: 120
​
currency_code
string

The three-character ISO-4217 currency code that identifies the currency.

Required string length: 3
​
memo
string

A private bookkeeping memo for the user.

Maximum string length: 500
​
total_amount_range
Amount Range · object

Filters the search by the total amount.

​
invoice_date_range
Date Range · object

Filters the search by a date range for the invoice, in Internet date and time format.

​
due_date_range
Date Range · object

Filters the search by a due date range for the invoice, in Internet date and time format.

​
payment_date_range
Date and Time Range · object

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

​
creation_date_range
Date and Time Range · object

Filters the search by a creation date range for the invoice, in Internet date and time format.

​
archived
boolean

Indicates whether to list merchant-archived invoices in the response. Value is:

  • true. Response lists only merchant-archived invoices.
  • false. Response lists only unarchived invoices.
  • null. Response lists all invoices.

​
fields
string[]

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 items, payments, refunds, additional_recipients_info, and attachments.

Maximum array length: 5

The name of the field.

Maximum string length: 2147483647

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that lists the invoices that match the search criteria.

An array of merchant invoices. Includes the total invoices count and HATEOAS links for navigation.

​
total_pages
integer

The total number of pages that are available for the search criteria.

Note: Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next

Required range: 0 <= x <= 2147483647
​
total_items
integer

The total number of invoices that match the search criteria.

Note: Clients MUST NOT assume that the value of total_items is constant. The value MAY change from one request to the next.

Required range: 0 <= x <= 2147483647
​
items
Invoice · object[]

The list of invoices that match the search criteria.

Maximum array length: 100
​
links
Link Description · object[]

An array of request-related HATEOAS links.

Maximum array length: 2147483647