Retrieve tax reports

DocsLimited

Last updated: Dec 10th, 10:45pm

You can retrieve Form 1099-K PDF documents for merchants who meet IRS reporting requirements. PayPal generates these reports annually and makes them available through the API by January 1 following the tax year.

List available tax reports

Use a valid access token and make a GET call to the /v2/taxes/reports endpoint.

Sample request
Sample response

1curl -X GET 'https://api-m.sandbox.paypal.com/v2/taxes/reports?report_type=1099-K&tax_year=2024' \
2-H 'Content-Type: application/json' \
3-H 'Authorization: Bearer <ACCESS-TOKEN>' \
4-H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>'

Parameter	Description
`report_type`	Type of tax report to retrieve. Use `1099-K` for Payment Settlement Entity reports.
`tax_year`	Four-digit year for which to retrieve reports. Example: `2024`.
`exclude`	Comma-separated list of fields to exclude from response. Use `files_info` to retrieve only report metadata without file download links.
`page`	Page number for pagination. Default is `1`.
`page_size`	Number of reports per page. Default is `100`, maximum is `100`.

On successful retrieval, the PayPal server returns tax reports with file download links.

Parameter	Description	Further action
`id`	Unique identifier for the tax report.	Get specific report details or submit corrections.
`account_id`	Encrypted merchant account identifier visible to partners.	Identify which merchant the report belongs to.
`corrected`	Indicates whether this is a corrected report. `true` means the report was regenerated after a correction request.	Identify corrected reports and notify merchants.
`status`	Report generation status. Possible values: `GENERATION_COMPLETED`, `GENERATED`, `IN_PROGRESS`, `FAILED`.	Download reports with `GENERATION_COMPLETED` or `GENERATED` status.
`files_info.files[].links`	HATEOAS links for file operations. The link with `rel: "self"` provides the PDF download URL.	Download the PDF file using the `href` value.

Get specific report details

Use a valid access token and make a GET call to the /v2/taxes/reports/{reportId} endpoint.

Path parameter: reportId is the unique identifier for the tax report, retrieved from the List available tax reports response.

Sample request
Sample response

1curl -X GET 'https://api-m.sandbox.paypal.com/v2/taxes/reports/11EF-CCBD-47F7C537-BADA-CB1E82FA8044' \
2-H 'Content-Type: application/json' \
3-H 'Authorization: Bearer <ACCESS-TOKEN>' \
4-H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>'

Download tax report PDF

Use a valid access token and make a GET call to the file download URL from the files_info.files[].links array.

1curl -X GET 'https://api-m.sandbox.paypal.com/v2/content/documents/CMP-044-11ef-ccbd-4c4e9b80-bd01-b6a073d4df5f/files/1/download' \
2-H 'Authorization: Bearer <ACCESS-TOKEN>' \
3-H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>' \
4--output 1099K_2024.pdf

The PDF file contains:

Merchant’s legal name and address.

Truncated TIN showing only the last 4 digits.

Monthly gross payment amounts for the tax year.

Total annual gross payment amount.

Payment card and third-party network transactions breakdown.

PayPal’s information as the Payment Settlement Entity and filer.

Note:The merchant copy shows only the last 4 digits of the TIN for security purposes. Forms filed with the IRS and state agencies include the full 9-digit TIN.

Handle webhook notifications

Configure your webhook handler to process tax reporting events and take appropriate action based on the event type. For webhook setup, see Set up webhook notifications.

TAXES.REPORTS.GENERATED

When you receive a TAXES.REPORTS.GENERATED webhook event, your webhook handler should:

Extract the resource.id value from the webhook payload.

Check the resource.corrected field to identify whether this is a regular or corrected report.

Use this report ID to get specific report details.

Download the PDF file using the file download link from the response.

Deliver the form to your merchant through your platform.

TAXES.REPORT.GENERATED (Regular report)
TAXES.REPORT.GENERATED (Corrected report)

1{
2     "id": "WH-7KS583797C273740K-4XG92085G17839137",
3     "event_version": "2.0",
4     "create_time": "2025-12-08T07:13:33.428Z",
5     "resource_type": "TAX-REPORT",
6     "resource_version": "2.0",
7     "event_type": "TAXES.REPORTS.GENERATED",
8     "summary": "TAX REPORT IS GENERATED.",
9     "resource": {
10          "account_id": "TMLTUT7USJQGY",
11          "create_time": "2025-12-08T07:13:28.661Z",
12          "files_info": {
13               "files": [
14                    {
15                         "sequence": 1,
16                         "name": "EXT-1764908915_1099K_2024_5328477226563214769_1765177982323.pdf",
17                         "links": [
18                              {
19                                   "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=1",
20                                   "rel": "self",
21                                   "method": "GET",
22                                   "encType": "application/json"
23                              },
24                              {
25                                   "href": "https://api.sandbox.paypal.com/v2/content/documents/CMP-044-11f0-d405-58f79170-873f-e0533e70ab97/files/1/download",
26                                   "rel": "download",
27                                   "method": "GET",
28                                   "encType": "application/json"
29                              }
30                         ]
31                    }
32               ],
33               "total_items": 1,
34               "links": [
35                    {
36                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
37                         "rel": "self",
38                         "method": "GET",
39                         "encType": "application/json"
40                    },
41                    {
42                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
43                         "rel": "first",
44                         "method": "GET",
45                         "encType": "application/json"
46                    },
47                    {
48                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
49                         "rel": "prev",
50                         "method": "GET",
51                         "encType": "application/json"
52                    },
53                    {
54                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
55                         "rel": "next",
56                         "method": "GET",
57                         "encType": "application/json"
58                    },
59                    {
60                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
61                         "rel": "last",
62                         "method": "GET",
63                         "encType": "application/json"
64                    }
65               ]
66          },
67          "total_files": 1,
68          "archive_time": "2035-12-06T07:13:28.661Z",
69          "links": [
70               {
71                    "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358",
72                    "rel": "self",
73                    "method": "GET",
74                    "encType": "application/json"
75               },
76               {
77                    "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358/corrections",
78                    "rel": "correction",
79                    "method": "POST",
80                    "encType": "application/json"
81               }
82          ],
83          "id": "11F0-D405-5519E21F-88AE-562A9B01F358",
84          "report_type": "1099-K",
85          "tax_year": 2024,
86          "corrected": false,
87          "status": "GENERATION_COMPLETED"
88     },
89     "links": [
90          {
91               "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-7KS583797C273740K-4XG92085G17839137",
92               "rel": "self",
93               "method": "GET"
94          },
95          {
96               "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-7KS583797C273740K-4XG92085G17839137/resend",
97               "rel": "resend",
98               "method": "POST"
99          }
100     ]
101}

Tax report lifecycle and availability

PayPal generates reports after the tax year ends and makes them available by January 1 of the year following the tax year.

PayPal retains reports for 10 years from the creation date.

PayPal generates a new report with corrected: true when you process corrections. The original report remains accessible.

You can access reports for multiple tax years through a single API endpoint.