Search Invoices

Use the /search-invoices resource to search for and list invoices that match search criteria.

Search for invoices

post

Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.

Authorizations

Query parameters

pageinteger · min: 1 · max: 1000Optional

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.

Default: 1

page_sizeinteger · min: 1 · max: 100Optional

The maximum number of templates to return in the response.

Default: 20

total_requiredbooleanOptional

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

Default: false

Body

The invoice search parameters.

recipient_emailstring · max: 254Optional

Filters the search by the email address.

recipient_first_namestring · max: 140Optional

Filters the search by the recipient first name.

recipient_last_namestring · max: 140Optional

Filters the search by the recipient last name.

recipient_business_namestring · max: 300Optional

Filters the search by the recipient business name.

invoice_numberstring · max: 25Optional

Filters the search by the invoice number.

referencestring · max: 120Optional

The reference data, such as a PO number.

currency_codestring · ppaas_common_currency_code_v2 · min: 3 · max: 3Optional

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

memostring · max: 500Optional

A private bookkeeping memo for the user.

archivedbooleanOptional

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.

fieldsstring[]Optional

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.

Responses

200

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

application/jsonmultipart/mixed

400

Invalid request.

application/jsonmultipart/mixed

403

Authorization Error.

application/jsonmultipart/mixed

default

The default response.

application/json

post

HTTPcURLJavaScriptPython

POST /v2/invoicing/search-invoices HTTP/1.1
Host: api-m.sandbox.paypal.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 197

{
  "total_amount_range": {
    "lower_amount": {
      "currency_code": "USD",
      "value": "50.00"
    },
    "upper_amount": {
      "currency_code": "USD",
      "value": "50.00"
    }
  },
  "invoice_date_range": {
    "start": "2018-06-01",
    "end": "2018-06-21"
  }
}

{
  "total_pages": 1,
  "total_items": 1,
  "items": [
    {
      "id": "text",
      "parent_id": "text",
      "status": "DRAFT",
      "detail": {
        "reference": "text",
        "currency_code": "text",
        "note": "text",
        "terms_and_conditions": "text",
        "memo": "text",
        "attachments": [
          {
            "id": "text",
            "reference_url": "https://example.com",
            "content_type": "text",
            "create_time": "text",
            "size": "text"
          }
        ],
        "invoice_number": "text",
        "invoice_date": "text",
        "payment_term": {
          "term_type": "DUE_ON_RECEIPT",
          "due_date": "text"
        },
        "metadata": {
          "create_time": "text",
          "created_by": "text",
          "last_update_time": "text",
          "last_updated_by": "text",
          "cancel_time": "text",
          "cancelled_by": "text",
          "first_sent_time": "text",
          "last_sent_time": "text",
          "last_sent_by": "text",
          "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP",
          "recipient_view_url": "https://example.com",
          "invoicer_view_url": "https://example.com"
        }
      },
      "invoicer": {
        "business_name": "text",
        "name": {
          "prefix": "text",
          "given_name": "text",
          "surname": "text",
          "middle_name": "text",
          "suffix": "text",
          "alternate_full_name": "text",
          "full_name": "text"
        },
        "address": {
          "address_line_1": "text",
          "address_line_2": "text",
          "address_line_3": "text",
          "admin_area_4": "text",
          "admin_area_3": "text",
          "admin_area_2": "text",
          "admin_area_1": "text",
          "postal_code": "text",
          "country_code": "text",
          "address_details": {
            "street_number": "text",
            "street_name": "text",
            "street_type": "text",
            "delivery_service": "text",
            "building_name": "text",
            "sub_building": "text"
          }
        },
        "email_address": "text",
        "phones": [
          {
            "country_code": "text",
            "national_number": "text",
            "extension_number": "text",
            "phone_type": "FAX"
          }
        ],
        "website": "https://example.com",
        "tax_id": "text",
        "additional_notes": "text",
        "logo_url": "https://example.com"
      },
      "primary_recipients": [
        {
          "billing_info": {
            "business_name": "text",
            "name": {
              "prefix": "text",
              "given_name": "text",
              "surname": "text",
              "middle_name": "text",
              "suffix": "text",
              "alternate_full_name": "text",
              "full_name": "text"
            },
            "address": {
              "address_line_1": "text",
              "address_line_2": "text",
              "address_line_3": "text",
              "admin_area_4": "text",
              "admin_area_3": "text",
              "admin_area_2": "text",
              "admin_area_1": "text",
              "postal_code": "text",
              "country_code": "text",
              "address_details": {
                "street_number": "text",
                "street_name": "text",
                "street_type": "text",
                "delivery_service": "text",
                "building_name": "text",
                "sub_building": "text"
              }
            },
            "email_address": "text",
            "phones": [
              {
                "country_code": "text",
                "national_number": "text",
                "extension_number": "text",
                "phone_type": "FAX"
              }
            ],
            "additional_info": "text",
            "language": "text"
          },
          "shipping_info": {
            "business_name": "text",
            "name": {
              "prefix": "text",
              "given_name": "text",
              "surname": "text",
              "middle_name": "text",
              "suffix": "text",
              "alternate_full_name": "text",
              "full_name": "text"
            },
            "address": {
              "address_line_1": "text",
              "address_line_2": "text",
              "address_line_3": "text",
              "admin_area_4": "text",
              "admin_area_3": "text",
              "admin_area_2": "text",
              "admin_area_1": "text",
              "postal_code": "text",
              "country_code": "text",
              "address_details": {
                "street_number": "text",
                "street_name": "text",
                "street_type": "text",
                "delivery_service": "text",
                "building_name": "text",
                "sub_building": "text"
              }
            }
          }
        }
      ],
      "additional_recipients": [
        "text"
      ],
      "items": [
        {
          "id": "text",
          "name": "text",
          "description": "text",
          "quantity": "text",
          "unit_amount": {
            "currency_code": "text",
            "value": "text"
          },
          "tax": {
            "name": "text",
            "percent": "text",
            "amount": {
              "currency_code": "text",
              "value": "text"
            }
          },
          "item_date": "text",
          "discount": {
            "percent": "text",
            "amount": {
              "currency_code": "text",
              "value": "text"
            }
          },
          "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": "text",
            "value": "text"
          }
        },
        "template_id": "PayPal system template"
      },
      "amount": {
        "currency_code": "text",
        "value": "text",
        "breakdown": {
          "item_total": {
            "currency_code": "text",
            "value": "text"
          },
          "discount": {
            "invoice_discount": {
              "percent": "text",
              "amount": {
                "currency_code": "text",
                "value": "text"
              }
            },
            "item_discount": {
              "currency_code": "text",
              "value": "text"
            }
          },
          "tax_total": {
            "currency_code": "text",
            "value": "text"
          },
          "shipping": {
            "amount": {
              "currency_code": "text",
              "value": "text"
            },
            "tax": {
              "name": "text",
              "percent": "text",
              "amount": {
                "currency_code": "text",
                "value": "text"
              }
            }
          },
          "custom": {
            "label": "text",
            "amount": {
              "currency_code": "text",
              "value": "text"
            }
          }
        }
      },
      "due_amount": {
        "currency_code": "text",
        "value": "text"
      },
      "gratuity": {
        "currency_code": "text",
        "value": "text"
      },
      "payments": {
        "paid_amount": {
          "currency_code": "text",
          "value": "text"
        },
        "transactions": [
          {
            "type": "PAYPAL",
            "payment_id": "text",
            "payment_date": "text",
            "method": "BANK_TRANSFER",
            "note": "text",
            "amount": {
              "currency_code": "text",
              "value": "text"
            },
            "shipping_info": {
              "business_name": "text",
              "name": {
                "prefix": "text",
                "given_name": "text",
                "surname": "text",
                "middle_name": "text",
                "suffix": "text",
                "alternate_full_name": "text",
                "full_name": "text"
              },
              "address": {
                "address_line_1": "text",
                "address_line_2": "text",
                "address_line_3": "text",
                "admin_area_4": "text",
                "admin_area_3": "text",
                "admin_area_2": "text",
                "admin_area_1": "text",
                "postal_code": "text",
                "country_code": "text",
                "address_details": {
                  "street_number": "text",
                  "street_name": "text",
                  "street_type": "text",
                  "delivery_service": "text",
                  "building_name": "text",
                  "sub_building": "text"
                }
              }
            }
          }
        ]
      },
      "refunds": {
        "refund_amount": {
          "currency_code": "text",
          "value": "text"
        },
        "transactions": [
          {
            "type": "PAYPAL",
            "refund_id": "text",
            "refund_date": "text",
            "amount": {
              "currency_code": "text",
              "value": "text"
            },
            "method": "BANK_TRANSFER"
          }
        ]
      },
      "links": [
        {
          "href": "text",
          "rel": "text",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "text",
      "rel": "text",
      "method": "GET"
    }
  ]
}