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": [
    {
      "id": "<string>",
      "parent_id": "<string>",
      "status": "DRAFT",
      "detail": {
        "reference": "<string>",
        "currency_code": "<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>"
        }
      },
      "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": {
          "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>",
          "country_code": "<string>",
          "address_details": {}
        },
        "email_address": "<string>",
        "phones": [
          {
            "country_code": "<string>",
            "national_number": "<string>",
            "extension_number": "<string>",
            "phone_type": "FAX"
          }
        ],
        "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": {
              "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>",
              "country_code": "<string>",
              "address_details": {}
            },
            "email_address": "<string>",
            "phones": [
              {
                "country_code": "<string>",
                "national_number": "<string>",
                "extension_number": "<string>",
                "phone_type": "FAX"
              }
            ],
            "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": {
              "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>",
              "country_code": "<string>",
              "address_details": {}
            }
          }
        }
      ],
      "additional_recipients": [
        "<string>"
      ],
      "items": [
        {
          "id": "<string>",
          "name": "<string>",
          "description": "<string>",
          "quantity": "<string>",
          "unit_amount": {
            "currency_code": "<string>",
            "value": "<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": [
          {
            "type": "PAYPAL",
            "payment_id": "<string>",
            "payment_date": "<string>",
            "payment_date_time": "<string>",
            "method": "BANK_TRANSFER",
            "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": {
                "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>",
                "country_code": "<string>",
                "address_details": {}
              }
            }
          }
        ]
      },
      "refunds": {
        "refund_amount": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "transactions": [
          {
            "type": "PAYPAL",
            "refund_id": "<string>",
            "refund_date": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "method": "BANK_TRANSFER"
          }
        ]
      },
      "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 <code>total_pages</code> and <code>total_items</code> 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 length: 254
​
recipient_first_name
string

Filters the search by the recipient first name.

Maximum length: 140
​
recipient_last_name
string

Filters the search by the recipient last name.

Maximum length: 140
​
recipient_business_name
string

Filters the search by the recipient business name.

Maximum length: 300
​
invoice_number
string

Filters the search by the invoice number.

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

An array of status values.

Maximum length: 5
​
reference
string

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

Maximum 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 length: 500
​
total_amount_range
object

Filters the search by the total amount.

​
invoice_date_range
object

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

​
due_date_range
object

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

​
payment_date_range
object

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

​
creation_date_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:<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
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 <code>items</code>, <code>payments</code>, <code>refunds</code>, <code>additional_recipients_info</code>, and <code>attachments</code>.

Maximum length: 5

The name of the field.

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. <blockquote><strong>Note:</strong> Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next</blockquote>

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

The total number of invoices that match the search criteria.<blockquote><strong>Note:</strong> Clients MUST NOT assume that the value of <code>total_items</code> is constant. The value MAY change from one request to the next.</blockquote>

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

The list of invoices that match the search criteria.

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

An array of request-related HATEOAS links.

Maximum length: 2147483647
⌘I