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
andpage_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.