Invoicing / Integrate / View Invoice Information

View Invoice Information


You can list all or a filtered set of invoices and show invoice details including status.

1. List invoices

Merchants can list all invoices.

By default, the response lists the first 20 invoices that belong to the merchant who makes the call.

To paginate the invoices that appear in the response, specify the optional page and page_size query parameters.

This sample request returns three pages of invoices with four invoices on each page:

curl -v -X GET \
  https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>"

A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices with invoice details:

{
  "total_count": 589,
  "invoices": [
  {
    "id": "INV2-RF6D-L66T-D7H2-CRU7",
    "number": "INV 01256",
    "status": "DRAFT",
    "merchant_info":
    {
      "email": "dlarusso@example.com",
      "first_name": "David",
      "last_name": "Larusso",
      "business_name": "Mitchell & Murray",
      "phone":
      {
        "country_code": "001",
        "national_number": "4085551234"
      },
      "address":
      {
        "line1": "1234 First Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "billing_info": [
    {
      "email": "stmeyers@example.com",
      "first_name": "Stephanie",
      "last_name": "Meyers"
    }],
    "shipping_info":
    {
      "first_name": "Stephanie",
      "last_name": "Meyers",
      "address":
      {
        "line1": "1234 Main Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "invoice_date": "2017-06-22 PDT",
    "note": "Thank you for your business.",
    "total_amount":
    {
      "currency": "USD",
      "value": "387.30"
    },
    "metadata":
    {
      "created_date": "2017-02-27 23:55:58 PST"
    }
  },
  {
    "id": "INV2-RF6D-L66T-D7H2-CRU7",
    "number": "9879878979003790",
    "status": "DRAFT",
    "merchant_info":
    {
      "email": "dlarusso@example.com",
      "first_name": "David",
      "last_name": "Larusso",
      "business_name": "Mitchell & Murray",
      "phone":
      {
        "country_code": "001",
        "national_number": "4085551234"
      },
      "address":
      {
        "line1": "1234 First Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "billing_info": [
    {
      "email": "stmeyers@example.com",
      "first_name": "Stephanie",
      "last_name": "Meyers"
    }],
    "shipping_info":
    {
      "first_name": "Stephanie",
      "last_name": "Meyers",
      "address":
      {
        "line1": "1234 Main Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "invoice_date": "2017-06-22 PDT",
    "note": "Thank you for your business.",
    "total_amount":
    {
      "currency": "USD",
      "value": "387.30"
    },
    "metadata":
    {
      "created_date": "2017-02-27 23:55:58 PST"
    }
  },
  {
    "id": "INV2-RF6D-L66T-D7H2-CRU7",
    "number": "9879878979003789",
    "status": "DRAFT",
    "merchant_info":
    {
      "email": "dlarusso@example.com",
      "first_name": "David",
      "last_name": "Larusso",
      "business_name": "Mitchell & Murray",
      "phone":
      {
        "country_code": "001",
        "national_number": "4085551234"
      },
      "address":
      {
        "line1": "1234 First Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "billing_info": [
    {
      "email": "stmeyers@example.com",
      "first_name": "Stephanie",
      "last_name": "Meyers"
    }],
    "shipping_info":
    {
      "first_name": "Stephanie",
      "last_name": "Meyers",
      "address":
      {
        "line1": "1234 Main Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "invoice_date": "2017-06-22 PDT",
    "note": "Thank you for your business.",
    "total_amount":
    {
      "currency": "USD",
      "value": "387.30"
    },
    "metadata":
    {
      "created_date": "2017-02-27 23:55:58 PST"
    }
  },
  {
    "id": "INV2-RF6D-L66T-D7H2-CRU7",
    "number": "9879878979003788",
    "status": "DRAFT",
    "merchant_info":
    {
      "email": "dlarusso@example.com",
      "first_name": "David",
      "last_name": "Larusso",
      "business_name": "Mitchell & Murray",
      "phone":
      {
        "country_code": "001",
        "national_number": "4085551234"
      },
      "address":
      {
        "line1": "1234 First Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "billing_info": [
    {
      "email": "stmeyers@example.com",
      "first_name": "Stephanie",
      "last_name": "Meyers"
    }],
    "shipping_info":
    {
      "first_name": "Stephanie",
      "last_name": "Meyers",
      "address":
      {
        "line1": "1234 Main Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "invoice_date": "2017-06-22 PDT",
    "note": "Thank you for your business.",
    "total_amount":
    {
      "currency": "USD",
      "value": "387.30"
    },
    "metadata":
    {
      "created_date": "2017-02-27 23:55:58 PST"
    }
  }],
  "links": [
  {
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=4&page_size=4&total_count_required=true",
    "rel": "next",
    "method": "GET"
  },
  {
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=2&page_size=4&total_count_required=true",
    "rel": "previous",
    "method": "GET"
  }]
}

2. Search for invoices

Merchants can list invoices that match search criteria, such as email, name, and invoice number.

If you pass multiple criteria, the response lists invoices that match all criteria.

  • By default, the response shows the first 20 invoices that belong to the calling merchant.
  • To paginate the results, include the optional page and page_size query parameters.
  • To filter the invoices that appear in the response, include one or more optional query parameters.

This sample request lists invoices for a specified date range:

curl -v -X POST \
  https://api-m.sandbox.paypal.com/v1/invoicing/search/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -d '{
  "start_invoice_date": "2017-01-01 PST",
  "end_invoice_date": "2017-12-31 PST",
  "page": 0,
  "page_size": 3,
  "total_count_required": true
}'

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

{
  "invoices": [
  {
    "id": "INV2-RF6D-L66T-D7H2-CRU7",
    "number": "INV 01256",
    "status": "DRAFT",
    "merchant_info":
    {
      "email": "dlarusso@example.com",
      "first_name": "David",
      "last_name": "Larusso",
      "business_name": "Mitchell & Murray",
      "phone":
      {
        "country_code": "001",
        "national_number": "4085551234"
      },
      "address":
      {
        "line1": "1234 First Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "billing_info": [
    {
      "email": "stmeyers@example.com",
      "first_name": "Stephanie",
      "last_name": "Meyers"
    }],
    "shipping_info":
    {
      "first_name": "Stephanie",
      "last_name": "Meyers",
      "address":
      {
        "line1": "1234 Main Street",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "98765",
        "country_code": "US"
      }
    },
    "items": [
    {
      "name": "Zoom System wireless headphones",
      "quantity": 2,
      "unit_price":
      {
        "currency": "USD",
        "value": "120.00"
      },
      "tax":
      {
        "name": "Tax",
        "percent": 8,
        "amount":
        {
          "currency": "USD",
          "value": "19.20"
        }
      }
    },
    {
      "name": "Bluetooth speaker",
      "quantity": 1,
      "unit_price":
      {
        "currency": "USD",
        "value": "145.00"
      },
      "tax":
      {
        "name": "Tax",
        "percent": 8,
        "amount":
        {
          "currency": "USD",
          "value": "11.60"
        }
      }
    }],
    "invoice_date": "2017-06-22 PDT",
    "discount":
    {
      "percent": 10,
      "amount":
      {
        "currency": "USD",
        "value": "38.50"
      }
    },
    "shipping_cost":
    {
      "amount":
      {
        "currency": "USD",
        "value": "10.00"
      }
    },
    "tax_calculated_after_discount": false,
    "tax_inclusive": false,
    "note": "Thank you for your business.",
    "total_amount":
    {
      "currency": "USD",
      "value": "387.30"
    },
    "metadata":
    {
      "created_date": "2017-06-22 09:39:04 PDT"
    }
  }]
}

3. Show invoice details

Merchants can show details for an invoice, by ID.

This sample request shows invoice details:

curl -v -X GET \
  https://api-m.sandbox.paypal.com/v1/invoicing/invoices/<invoice_id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>"

A successful request returns the HTTP 200 OK status code and a JSON response body that shows invoice details:

{
  "id": "INV2-RF6D-L66T-D7H2-CRU7",
  "number": "0002",
  "status": "DRAFT",
  "template_id": "TEMP-XYZ",
  "merchant_info":
  {
    "logo_url": "https://pics.paypal.com/00/s/MjA2WDE4NzRYUE5H/p/ZDBlYzMxOTctZDE0Ni00ZmQ0LThkZTgtNGU5YzYyNjg3OTRh/image_109.PNG",
    "email": "dlarusso@example.com",
    "first_name": "David",
    "last_name": "Larusso",
    "business_name": "Mitchell & Murray",
    "phone":
    {
      "country_code": "001",
      "national_number": "4085551234"
    },
    "address":
    {
      "line1": "1234 First Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "98765",
      "country_code": "US"
    }
  },
  "billing_info": [
  {
    "email": "stmeyers@example.com",
    "first_name": "Stephanie",
    "last_name": "Meyers"
  }],
  "shipping_info":
  {
    "first_name": "Stephanie",
    "last_name": "Meyers",
    "address":
    {
      "line1": "1234 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "98765",
      "country_code": "US"
    }
  },
  "items": [
  {
    "name": "Zoom System wireless headphones",
    "quantity": 2,
    "unit_price":
    {
      "currency": "USD",
      "value": "120.00"
    },
    "tax":
    {
      "name": "Tax",
      "percent": 8
    }
  },
  {
    "name": "Bluetooth speaker",
    "quantity": 1,
    "unit_price":
    {
      "currency": "USD",
      "value": "145.00"
    },
    "tax":
    {
      "name": "Tax",
      "percent": 8
    }
  }],
  "invoice_date": "2017-06-22 PDT",
  "discount":
  {
    "percent": 10,
    "amount":
    {
      "currency": "USD",
      "value": "38.50"
    }
  },
  "shipping_cost":
  {
    "amount":
    {
      "currency": "USD",
      "value": "10.00"
    }
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Thank you for your business.",
  "total_amount":
  {
    "currency": "USD",
    "value": "387.30"
  },
  "metadata":
  {
    "created_date": "2017-06-22 09:39:04 PDT"
  },
  "allow_tip": false,
  "links": [
  {
    "rel": "self",
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
    "method": "GET"
  },
  {
    "rel": "send",
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7/send",
    "method": "POST"
  },
  {
    "rel": "update",
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7/update",
    "method": "PUT"
  },
  {
    "rel": "delete",
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
    "method": "DELETE"
  }]
}

Next step

Continue to Remove Invoices.